march 9 release

# Azure PowerShell Release Notes

The following list outlines the steps necessary for a successful release of Azure PowerShell. Please check off the boxes as you complete the steps.

## Prerequisites
- [ ] On aka.ms, request access to `azure-powershellget` (redirect link for Azure PowerShell), `azure-powershellget2` (second redirect link for Azure PowerShell), `azps-release` (redirect link to GitHub release) and `azure-powershellvs` (redirect link for Azure Stack)
- [ ] Join the Microsoft organization on GitHub to gain access to the [`WebPlatformInstallerFeed`](https://github.com/Microsoft/WebPlatformInstallerFeed) repository
	- _Note_: you can join this organization on the same page that you join the Azure organization (https://aka.ms/azuregithub)
	- After gaining access to this repository, create your own fork and clone it to your machine
- [ ] Install Orca
	- You can find a link to the msi here: `\\aaptfile01\ADXSDK\PowerShell\Orca.msi`

## Release Process
- [ ] For all existing PRs in the `azure-powershell` repo targeting the `preview` branch, run the `powershell-demand` Jenkins job on each one, and merge if the build is successful, does not conflict with the `preview` branch, and has been signed off by a member of the team
- [ ] Run the `powershell-demand` Jenkins job against the `preview` branch and fix any issues if the build is not green
- [ ] In the Azure PowerShell repo, create a branch for the release and name it `release-X.X.X`
- [ ] Restrict access to the release branch through the GitHub settings so partners cannot merge their PRs themselves
    - In the settings window, find the `Protected branches` section, and select the release branch from the drop-down menu
    - Make sure the following are the only things checked off:
        + *Protect this branch*
		+ _Require pull request reviews before merging_
		    + _Dismiss stale pull request approvals when new commits are pushed_
        + *Require status checks to pass before merging*
	        + *default* (located under **Status checks found in the last week for this repository**)
		+ *continuous-integration/travis-ci*
		+ *license/cla*
        + *Restrict who can push to this branch*
            * Make sure to add *Azure/adx-sdk-manage* to this list of people with push access
    - You can check the settings for the `preview` branch if you have any questions
- [ ] Clone your fork of the Azure PowerShell repo to your computer, and switch to the release branch
    - Make sure to run `git clean -xdf` to wipe any changes from a previous branch
    - Rebuild the solution by opening the VS Developer Prompt and running `msbuild build.proj`
    
    
    
- Versioning tool
    
    
    
- [ ] Create a pull request (targeted at the release branch) with these changes to the versions
	- Kick off a `ps-sign` job based on this pull request to ensure that all packages are signed and show up in the `Build Artifacts`
	- Kick off a `powershell-demand` job based on this pull request
	- Merge the pull request when all jobs have passed and have been signed-off (_i.e._, successfull installation verification and passed all smoke tests)
- [ ] From the above `ps-sign` job, click on `Build Artifacts` download the zip, and unzip it somewhere on your machine
    - This zip file will contain the .msi for Azure PowerShell, and all of its .nupkg packages
- [ ] Navigate to `\\aaptfile01\ADXSDK\PowerShell` and create a new folder the release
	- Follow the format of previous release folders: `yyyy_mm_dd_PowerShell`
- [ ] Copy the contents from the `PSReleaseDrop` folder to the folder you just created
	- The contents include:
		- `scripts` folder
		- `README.txt`
		- `RegisterRepository.ps1`
		- `removewebpiReg.reg`
		- `webpiReg.reg`
		- `wpilauncher.exe`
- [ ] Open the `webpiReg.reg` file and make sure that `ProductXmlLocation` is updated with the new shared folder path
- [ ] Copy the msi (from the achive folder you unzipped) over to the shared folder you created above, renaming it to `azure-powershell.X.X.X.msi`
- [ ] Create a folder called `pkgs` in the shared folder and copy the `.nupkg` files from `archive/src/Package` into it
- [ ] Run Orca and drag `azure-powershell.X.X.X.msi` into the window. On the left side of the window, click `Property` and copy the entry for `ProductCode`
- [ ] In your cloned `WebPlatformInstaller` repository, create a new branch called `release-X.X.X`.
- [ ] Modify `Src/azuresdk/AzurePS/DH_AzurePS.xml`
	- Copy the last `<discoveryHint>` entry  (including `<msiProductCode>`) who shares the same `<msiProductCode>` as the discovery hint in `DH_WindowsAzurePowerShellGet`. Paste those three lines after the three lines you just copied, and update the `<msiProductCode>` with the `ProductCode` you retrieved earlier
	- Update the `<msiProductCode>` entry in `DH_WindowsAzurePowerShellGet` with the `ProductCode` you retrieved earlier
- [ ] Modify `Src/azuresdk/AzurePS/WebProductList_AzurePS.xml`
	- Find the section for `<productId>WindowsAzurePowerShellGet</productId>`
	- Update the `<version>` entry
	- Update the `<published>` and `<updated>` entries to the date of the release
	- Update the version in _both_ `<trackingURL>` entries
	- Update _both_ `<installerURL>` entries to point at the shared folder you created
- [ ] Using `cmd`, navigate to `WebPlatformInstaller/Tools` and run `Build.cmd`
- [ ] Copy the `.xml` files from `WebPlatformInstaller/bin` and paste them into the shared folder

### Testing the RC


- Testing scenarios


- [ ] Once all of the tests have passed, send an email to [all partners](mailto:[email protected]) with the path to the shared folder
    - Make sure to tell the partners to update their change log with any changes that they made that aren't currently found in it for the release
    - Copy the e-mail contents and post it on the slack channels ([`#powershell`](https://azuresdk.slack.com/messages/powershell/) and [`#powershell-announce`](https://azuresdk.slack.com/messages/powershell-announce/))
- [ ] After the initial release candidate was sent out, give the partner teams three business days to sign off
- [ ] Run the `tools\UpdateChangeLog.ps1` script to update the root change log to include all of the changes made this release to each service
    - Create a pull request to submit these changes to the release branch and make sure that all of the change logs get updated properly and that the psd1 files include the changes in their release notes
- [ ] Give anyone with an open PR, or those that are creating a new PR making quick additions, a chance to target the release branch, get their code reviewed, and run a successful `powershell-demand` job
- [ ] Once candidate PRs are either merged or pushed back, run the `powershell-sign` job on the release branch and notify partner teams of this release candidate
    - **Note:** For additional release candidates created, make sure to update the `DH_AzurePS.xml` file with the new product code of the .msi (obtained from Orca) and regenerate the other .xml files as mentioned previously (or with the `BuildDrop.ps1` script)
- [ ] After the final release candidate is out, push the modules to the test gallery using the `ModulePublisher` module. To install the modules necessary for test publishing to the gallery, open up a new PowerShell window, change your directory to the **scripts** folder in the registry entry, and run the following command:
    ```powershell 
    Import-Module "ModulePublisher\ModulePublisher.psd1"
    ```
- [ ] Use `Login-AzureRmAccount` to login to your corporate account
- [ ] Run the following command to test publishing to the gallery
    ```powershell
    Publish-RMModules $Path $NugetExe $RepoName -WhatIf
    ```
    - `$Path` is the path to the `pkgs` folder (you may want to copy these files somewhere locally so you don't have to get them from the shared folder)
    - `$NugetExe` is the path to the `nuget.exe` file on your computer
    - `$RepoName` is the name of the gallery you are pushing to, so in this case, it will be `TestGallery`
    - `WhatIf` is a SwitchParameter that will allow you to see in what order the modules will be published. You want to make sure that `AzureRM.Profile` will be published first, followed by `AzureRM.Storage`, and then `Azure`, and the last module to be published is `AzureRM`. Once you see that this is the correct ordering of modules, remove the `WhatIf` parameter to push them to the test gallery.
    - **NOTE**: make sure that the "Release Notes" section of `AzureRM.psd1` do not contain more than 10,000 characters, or the push to the gallery will fail
- [ ] Smoke test these modules with the same steps used above for testing
- [ ] Install [Azure Storage Explorer](https://azurestorageexplorer.codeplex.com/) and upload the .msi file to the download blob container
    - The storage account name and storage account key can be retrieved from KeyVault
    - Upload the `azure-powershell.X.X.X.msi` file from the shared folder to the latest downloads folder
- [ ] Update `aka.ms/azure-powershellget` or `aka.ms/azure-powershellget2` with the link to the msi you just uploaded to Storage Explorer
    - You will update whichever aka.ms link contains the older Azure PowerShell msi. For example, if `azure-powershellget` contains a link to 3.0.0, and `azure-powershellget2` contains a link to 3.1.0, you will update `azure-powershellget` (since it contains the older of the two links)
- [ ] Submit a pull request to the WebPI feed and send an email to Chris Sfanos asking to merge the PR at the time of the release
    - The pull request should just include changes to the `WebProductList_AzurePS.xml` and `DH_AzurePS.xml` files
    - **Note**: make sure that the changes to the *installerUrl* have been reverted to the `aka.ms` links and that they point to the `aka.ms` link that was updated in the previous step
- [ ] Follow the same steps for test publishing, except `$RepoName` will now be `PSGallery`
    - It may be helpful to run the command with the `WhatIf` parameter to make sure that `Profile` is being published first, `Storage` is published second, and `AzureRM` is published last'
    - **NOTE**: update the release notes in each psd1 file to include a link to the change log from the public GitHub Release that we just created
- [ ] Follow the same steps for smoke testing that we followed above
- [ ] Smoke test the live WebPI feed
- [ ] Create a public GitHub [Release](https://github.com/Azure/azure-powershell/releases) with appropriate tag
    - Use the change log from this release as the content of the document
    - Include the .msi file and include a link to it at the top of the document with "Installer: Windows Standalone"
    - Include the changes since the last release at the end of the document
- [ ] Send an email to [all partners](mailto:[email protected]) with the locations of where the release can be accessed: the PowerShell Gallery modules (both Azure and AzureRM), the WebPI feed, and the GitHub release
    - Copy the e-mail contents and post it on the slack channels (specifically [`#powershell`](https://azuresdk.slack.com/messages/powershell/) and [`#powershell-announce`](https://azuresdk.slack.com/messages/powershell-announce/))
- [ ] Create a pull request to merge the release branch to master, and then merge it once the build passes
- [ ] Delete the release branch
- [ ] Create a pull request to merge the master branch to dev, and then merge it once the build passes
- [ ] Resolve any issues, close the release milestone, and create a new milestone for +3 months
    - Contact partners about any of their bugs still open in the release milestone, and ensure that all bugs are either closed or moved into the appropriate milestone

## Testing

### Setting up the Repository

Place the `.nupkg` files from this release and the previous release in a common folder on your machine. Run the following command to register the repository:

```powershell
Register-PSRepository -Name {{repositoryName}} -SourceLocation {{folderPath}} -PackageManagementProvider NuGet -InstallationPolicy Trusted
```

### Clean Install of AzureRM

```powershell
Install-Module -Name AzureRM -Repository {{repositoryName}}

.\RunInstallationTests.ps1
```

### Update AzureRM

```powershell
Install-Module -Name AzureRM -Repository {{repositoryName}} -RequiredVersion {{previousVersion}}

Update-Module -Name AzureRM
.\RunInstallationTests.ps1
```

### Clean Install of Individual Module

```powershell
Install-Module -Name AzureRM.Compute -Repository {{repositoryName}}

Get-AzureRmVM

Get-Module
```

### Update Individual Module

```powershell
Install-Module -Name AzureRM.Compute -Repository {{repositoryName}} -RequiredVersion {{previousVersion}}

Update-Module -Name AzureRM.Compute

Get-AzureRmVM

Get-Module
```

### Install AzureRM on top of Individual Module

```powershell

```

### Install Individual Module on top of AzureRM

```powershell

```