release0309.md

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 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 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 and #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:

  Import-Module "ModulePublisher\ModulePublisher.psd1"

• Use Login-AzureRmAccount to login to your corporate account

• Run the following command to test publishing to the gallery

  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 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 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 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 and #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:

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

Clean Install of AzureRM

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

.\RunInstallationTests.ps1

Update AzureRM

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

Update-Module -Name AzureRM
.\RunInstallationTests.ps1

Clean Install of Individual Module

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

Get-AzureRmVM

Get-Module

Update Individual Module

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

Install Individual Module on top of AzureRM