Update the releasing documentation to reflect the desired release steps and order (#3938)
* Update release documentation to reflect the desired release steps and order. * Update in-doc links * Update .spelling * Address comments * Additional changes to build/package example * Update .spelling * Remove another internal URL * Name and link updates could be automated * Move 'Note' to the top of 'Release Steps' section
This commit is contained in:
Dongbo Wang
Mike Richmond
parent
9eed401427
commit
7681fe9585
@ -296,6 +296,11 @@ vors
|
||||
- docs/maintainers/releasing.md
|
||||
2012r2
|
||||
CHANGELOG.md
|
||||
Dockerfiles
|
||||
downlevel
|
||||
Effing
|
||||
PowerShellCore
|
||||
Ronn
|
||||
Toolset
|
||||
v6
|
||||
WiX
|
||||
|
||||
@ -1,77 +1,72 @@
|
||||
Release Checklist
|
||||
=================
|
||||
* Summarize major changes since the previous release.
|
||||
* Update [CHANGELOG.md](../../CHANGELOG.md) with the major change list.
|
||||
* Create an [annotated tag][tag] for the release, with the major change list as the message.
|
||||
* Push the release tag, and create a release draft with the major change list.
|
||||
* Build packages and add them to the release draft.
|
||||
* Create NuGet packages and publish them to [powershell-core feed][ps-core-feed].
|
||||
* Publish the release draft.
|
||||
* Update documentation and scripts to use the links to new packages.
|
||||
* Push a branch named `docker` to `powershell/powershell` repository to trigger building docker images.
|
||||
* Delete the `docker` branch once the builds are successful at [powershell docker hub](https://hub.docker.com/r/microsoft/powershell/builds/).
|
||||
# PowerShell Core Releasing Process
|
||||
|
||||
Preparing
|
||||
=========
|
||||
## Release Steps
|
||||
|
||||
PowerShell releases use [Semantic Versioning][semver].
|
||||
Until we hit 6.0, each sprint results in a bump to the build number,
|
||||
so `v6.0.0-alpha.7` goes to `v6.0.0-alpha.8`.
|
||||
> Note: Step 2, 3 and 4 can be done in parallel. Step 5 and 6 can be done in parallel.
|
||||
|
||||
When a particular commit is chosen as a release,
|
||||
we create an [annotated tag][tag] that names the release,
|
||||
and list the major changes since the previous release.
|
||||
An annotated tag has a message (like a commit),
|
||||
and is *not* the same as a lightweight tag.
|
||||
Create one with `git tag -a v6.0.0-alpha.7`.
|
||||
Our convention is to prepend the `v` to the semantic version.
|
||||
The summary (first line) of the annotated tag message should be the full release title,
|
||||
e.g. 'v6.0.0-alpha.7 release of PowerShell'.
|
||||
1. Create a branch named `release` in `PowerShell/PowerShell` repository. All release related changes should happen in this branch.
|
||||
1. Prepare packages
|
||||
- [Build release packages](#building-packages)
|
||||
- Sign the MSI packages and DEB/RPM packages.
|
||||
- Install and verify the packages.
|
||||
1. Update documentation, scripts and Dockerfiles
|
||||
- Summarize the change log for the release. It should be reviewed by PM(s) to make it more user-friendly.
|
||||
- Update [CHANGELOG.md](../../CHANGELOG.md) with the finalized change log draft.
|
||||
- Update other documents and scripts to use the new package names and links.
|
||||
1. Verify the release Dockerfiles.
|
||||
1. Publish Linux packages to Microsoft YUM/APT repositories.
|
||||
1. [Create NuGet packages](#nuget-packages) and publish them to [powershell-core feed][ps-core-feed].
|
||||
1. [Create the release tag](#release-tag) and push the tag to `PowerShell/PowerShell` repository.
|
||||
1. Merge the `release` branch to `master` and delete the `release` branch.
|
||||
1. Publish the release in Github.
|
||||
1. Trigger the release docker builds for Linux and Windows container images.
|
||||
- Linux: push a branch named `docker` to `powershell/powershell` repository to trigger the build at [powershell docker hub](https://hub.docker.com/r/microsoft/powershell/builds/).
|
||||
Delete the `docker` branch once the builds succeed.
|
||||
- Windows: queue a new build in `PowerShell Windows Docker Build` on VSTS.
|
||||
1. Verify the generated docker container images.
|
||||
1. [Update the homebrew formula](#homebrew) for the OSX package.
|
||||
This task usually will be taken care of by the community,
|
||||
so we can wait for one day or two and see if the homebrew formula has already been updated,
|
||||
and only do the update if it hasn't.
|
||||
|
||||
While creating a release, it is advised to make a new branch such that
|
||||
necessary documentation updates and hot fixes can be made,
|
||||
without having to include all changes made to master.
|
||||
This release branch can be reviewed by the normal PR process.
|
||||
## Building Packages
|
||||
|
||||
When the annotated tag is finalized, push it with `git push --tags`.
|
||||
GitHub will see the tag and present it as an option when creating a new [release][].
|
||||
Start the release, use the annotated tag's summary as the title,
|
||||
and save the release as a draft while you upload the binary packages.
|
||||
> Note: Linux and Windows packages are taken care of by our release build pipeline in VSTS,
|
||||
while the OSX package needs to be built separately on a macOS.
|
||||
|
||||
Just as important as creating the release is updating the links on our readme,
|
||||
and the package names in the installation instructions.
|
||||
The AppVeyor build number should also be incremented.
|
||||
The release build should be started based on the `release` branch.
|
||||
The release Git tag won't be created until all release preparation tasks are done,
|
||||
so the to-be-used release tag should be passed to the release build as an argument.
|
||||
|
||||
When creating the packages, please ensure that the file path does not contain user names.
|
||||
> When creating the packages, please ensure that the file path does not contain user names.
|
||||
That is, clone to `/PowerShell` on Unix, and `C:\PowerShell` for Windows.
|
||||
The debug symbols include the absolute path to the sources when built,
|
||||
so it should appear `/PowerShell/src/powershell/System.Management.Automation`,
|
||||
not `/home/username/src/PowerShell/...`.
|
||||
|
||||
[semver]: http://semver.org/
|
||||
[tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
|
||||
[release]: https://help.github.com/articles/creating-releases/
|
||||
|
||||
Building Packages
|
||||
=================
|
||||
### Packaging Overview
|
||||
|
||||
The `build.psm1` module contains a `Start-PSPackage` function to build packages.
|
||||
It **requires** that `Start-PSBuild -CrossGen -PSModuleRestore` has been run.
|
||||
It **requires** that PowerShell Core has been built via `Start-PSBuild`.
|
||||
|
||||
Linux / macOS
|
||||
------------
|
||||
#### Windows
|
||||
|
||||
### Overview
|
||||
The `Start-PSPackage` function delegates to `New-MSIPackage` which creates a Windows Installer Package of PowerShell.
|
||||
The packages *must* be published in release mode,
|
||||
so make sure `-Configuration Release` is specified when running `Start-PSBuild`.
|
||||
|
||||
It uses the Windows Installer XML Toolset (WiX) to generate a MSI package,
|
||||
which copies the output of the published PowerShell files to a version-specific folder in Program Files,
|
||||
and installs a shortcut in the Start Menu.
|
||||
It can be uninstalled through `Programs and Features`.
|
||||
|
||||
Note that PowerShell is always self-contained, thus using it does not require installing it.
|
||||
The output of `Start-PSBuild` includes a `powershell.exe` executable which can simply be launched.
|
||||
|
||||
#### Linux / macOS
|
||||
|
||||
The `Start-PSPackage` function delegates to `New-UnixPackage`.
|
||||
This function will automatically deduce the correct version from the most recent annotated tag (using `git describe`).
|
||||
|
||||
At this time, each package must be made on the corresponding platform.
|
||||
The packages each have the .NET Core runtime-identifier appended to their filename.
|
||||
This is necessary to differentiate the Ubuntu 14.04 and 16.04 packages,
|
||||
which must be separate due to having different dependencies.
|
||||
|
||||
The `Start-PSPackage` function relies on the [Effing Package Management][fpm] project,
|
||||
It relies on the [Effing Package Management][fpm] project,
|
||||
which makes building packages for any (non-Windows) platform a breeze.
|
||||
Similarly, the PowerShell man-page is generated from the Markdown-like file
|
||||
[`assets/powershell.1.ronn`][man] using [Ronn][].
|
||||
@ -85,8 +80,6 @@ license, category, dependencies, and file layout).
|
||||
> Note that the only configuration on Linux and macOS is `Linux`,
|
||||
> which is release (i.e. not debug) configuration.
|
||||
|
||||
### Side-By-Side Design
|
||||
|
||||
To support side-by-side Unix packages, we use the following design:
|
||||
|
||||
We will maintain a `powershell` package
|
||||
@ -131,122 +124,56 @@ the versioned `powershell6.0` package.
|
||||
Without `-Name` specified, the primary `powershell`
|
||||
package will instead be created.
|
||||
|
||||
### macOS Package Creation
|
||||
|
||||
On macOS, create a new branch at the release tag. For example:
|
||||
``` powershell
|
||||
git checkout -b local-release-branch v6.0.0-alpha.11
|
||||
```
|
||||
Then run the following commands:
|
||||
``` powershell
|
||||
Import-Module ./build.psm1
|
||||
Start-PSBootstrap -Package
|
||||
Start-PSBuild -Crossgen -PSModuleRestore
|
||||
Start-PSPackage
|
||||
```
|
||||
|
||||
### Linux Package Creation
|
||||
|
||||
To create packages for the supported Linux distros,
|
||||
you can either run `Start-PSPackage` manually on each of the Linux distros or use Docker Build.
|
||||
|
||||
#### Manual Steps
|
||||
|
||||
On a supported Linux distro, Ubuntu 14.04 for instance, create a new branch at the release tag. For example:
|
||||
``` powershell
|
||||
git checkout -b local-release-branch v6.0.0-alpha.11
|
||||
```
|
||||
Then run the following commands:
|
||||
``` powershell
|
||||
Import-Module ./build.psm1
|
||||
Start-PSBootstrap -Package
|
||||
Start-PSBuild -Crossgen -PSModuleRestore
|
||||
Start-PSPackage
|
||||
```
|
||||
Repeat the steps on other supported Linux distros to generate the corresponding powershell core packages.
|
||||
|
||||
#### Docker Build
|
||||
|
||||
- Install Docker on Linux following [`docker/README.md`][docker-readme].
|
||||
If the Docker container cannot access internet after installation,
|
||||
you may be able to fix it in [this way][docker-network-fix].
|
||||
- In bash, run `/PowerShell/docker/launch.sh` with the release tag.
|
||||
It will start building 3 Docker images in parallel -- CentOS7, Ubuntu 14.04 and Ubuntu 16.04.
|
||||
When it's done, the created packages will be copied to "/PowerShell/docker/packages". For example:
|
||||
``` sh
|
||||
cd /PowerShell/docker
|
||||
BUILDS=nightly BRANCH=v6.0.0-alpha.11 ./launch.sh
|
||||
```
|
||||
- You can verify each package by starting a container of the corresponding Docker image.
|
||||
The created package is installed on the Docker image as the last step of building it.
|
||||
For example:
|
||||
``` sh
|
||||
docker run -it --rm microsoft/powershell-nightly:ubuntu16.04
|
||||
```
|
||||
|
||||
[fpm]: https://github.com/jordansissel/fpm
|
||||
[man]: ../../assets/powershell.1.ronn
|
||||
[ronn]: https://github.com/rtomayko/ronn
|
||||
[docker-readme]: ../../docker/README.md
|
||||
[docker-network-fix]: https://github.com/docker/docker/issues/1809#issuecomment-24080655
|
||||
|
||||
Windows
|
||||
-------
|
||||
### Build and Packaging Examples
|
||||
|
||||
### Overview
|
||||
On macOS or a supported Linux distro, run the following commands:
|
||||
|
||||
The `Start-PSPackage` function delegates to `New-MSIPackage` which creates a Windows Installer Package of PowerShell.
|
||||
The packages *must* be published in release mode, so use `Start-PSBuild -CrossGen -PSModuleRestore -Configuration Release`.
|
||||
It uses the Windows Installer XML Toolset (WiX) to generate a `PowerShell_<version>.msi`,
|
||||
which installs a self-contained copy of the current version (commit) of PowerShell.
|
||||
It copies the output of the published PowerShell application to a version-specific folder in Program Files,
|
||||
and installs a shortcut in the Start Menu.
|
||||
It can be uninstalled through Programs and Features.
|
||||
|
||||
Note that PowerShell is always self-contained, thus using it does not require installing it.
|
||||
The output of `Start-PSBuild` includes a `powershell.exe` executable which can simply be launched.
|
||||
|
||||
### Package Creation
|
||||
|
||||
To create release packages, create a new branch at the release tag. For example:
|
||||
``` powershell
|
||||
git checkout -b local-release-branch v6.0.0-alpha.11
|
||||
```
|
||||
|
||||
#### Windows 10 and Server 2016
|
||||
|
||||
``` powershell
|
||||
Import-Module .\build.psm1
|
||||
```powershell
|
||||
# Install dependencies
|
||||
Start-PSBootstrap -Package
|
||||
Start-PSBuild -Clean -CrossGen -PSModuleRestore -Runtime win10-x64 -Configuration Release
|
||||
Start-PSPackage -Type msi
|
||||
Start-PSPackage -Type zip
|
||||
|
||||
# Build for v6.0.0-beta.1 release
|
||||
Start-PSBuild -Clean -Crossgen -PSModuleRestore -ReleaseTag v6.0.0-beta.1
|
||||
|
||||
# Create package for v6.0.0-beta.1 release
|
||||
Start-PSPackage -ReleaseTag v6.0.0-beta.1
|
||||
```
|
||||
|
||||
#### Windows 8.1 and Server 2012r2
|
||||
On Windows, the `-Runtime` parameter should be specified for `Start-PSBuild` to indicate what version of OS the build is targeting.
|
||||
|
||||
``` powershell
|
||||
Import-Module .\build.psm1
|
||||
```powershell
|
||||
# Install dependencies
|
||||
Start-PSBootstrap -Package
|
||||
Start-PSBuild -Clean -CrossGen -PSModuleRestore -Runtime win81-x64 -Configuration Release
|
||||
Start-PSPackage -Type msi -WindowsDownLevel win81-x64
|
||||
Start-PSPackage -Type zip -WindowsDownLevel win81-x64
|
||||
|
||||
# Build for v6.0.0-beta.1 release targeting Windows 10 and Server 2016
|
||||
Start-PSBuild -Clean -CrossGen -PSModuleRestore -Runtime win10-x64 -Configuration Release -ReleaseTag v6.0.0-beta.1
|
||||
```
|
||||
|
||||
NuGet Packages
|
||||
==============
|
||||
If the package is targeting a downlevel Windows (not Windows 10 or Server 2016),
|
||||
the `-WindowsDownLevel` parameter should be specified for `Start-PSPackage`.
|
||||
Otherwise, the `-WindowsDownLevel` parameter should be left out.
|
||||
|
||||
Create a new branch at the release tag. For example:
|
||||
``` powershell
|
||||
git checkout -b local-release-branch v6.0.0-alpha.11
|
||||
```powershell
|
||||
# Create packages for v6.0.0-beta.1 release targeting Windows 10 and Server 2016.
|
||||
# When creating packages for downlevel Windows, such as Windows 8.1 or Server 2012R2,
|
||||
# the parameter '-WindowsDownLevel' must be specified.
|
||||
Start-PSPackage -Type msi -ReleaseTag v6.0.0-beta.1 <# -WindowsDownLevel win81-x64 #>
|
||||
Start-PSPackage -Type zip -ReleaseTag v6.0.0-beta.1 <# -WindowsDownLevel win81-x64 #>
|
||||
```
|
||||
|
||||
Run `Publish-NuGetFeed` to generate PowerShell NuGet packages:
|
||||
``` powershell
|
||||
Import-Module .\build.psm1
|
||||
Start-PSBootstrap -Package
|
||||
Start-PSBuild -Clean -Publish
|
||||
$VersionSuffix = ((git describe) -split '-')[-1]
|
||||
## NuGet Packages
|
||||
|
||||
In the `release` branch, run `Publish-NuGetFeed` to generate PowerShell NuGet packages:
|
||||
|
||||
```powershell
|
||||
# Assume the to-be-used release tag is 'v6.0.0-beta.1'
|
||||
$VersionSuffix = ("v6.0.0-beta.1" -split '-')[-1]
|
||||
|
||||
# Generate NuGet packages
|
||||
Publish-NuGetFeed -VersionSuffix $VersionSuffix
|
||||
```
|
||||
|
||||
@ -256,13 +183,37 @@ Maintainers are working on including the assemblies built for non-Windows platfo
|
||||
|
||||
[ps-core-feed]: https://powershell.myget.org/gallery/powershell-core
|
||||
|
||||
## Release Tag
|
||||
|
||||
Homebrew
|
||||
========
|
||||
PowerShell releases use [Semantic Versioning][semver].
|
||||
Until we hit 6.0, each sprint results in a bump to the build number,
|
||||
so `v6.0.0-alpha.7` goes to `v6.0.0-alpha.8`.
|
||||
|
||||
When a particular commit is chosen as a release,
|
||||
we create an [annotated tag][tag] that names the release.
|
||||
An annotated tag has a message (like a commit),
|
||||
and is *not* the same as a lightweight tag.
|
||||
Create one with `git tag -a v6.0.0-alpha.7 -m <message-here>`,
|
||||
and use the release change logs as the message.
|
||||
Our convention is to prepend the `v` to the semantic version.
|
||||
The summary (first line) of the annotated tag message should be the full release title,
|
||||
e.g. 'v6.0.0-alpha.7 release of PowerShellCore'.
|
||||
|
||||
When the annotated tag is finalized, push it with `git push --tags`.
|
||||
GitHub will see the tag and present it as an option when creating a new [release][].
|
||||
Start the release, use the annotated tag's summary as the title,
|
||||
and save the release as a draft while you upload the binary packages.
|
||||
|
||||
[semver]: http://semver.org/
|
||||
[tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
|
||||
[release]: https://help.github.com/articles/creating-releases/
|
||||
|
||||
## Homebrew
|
||||
|
||||
After the release, you can update homebrew formula.
|
||||
|
||||
On macOS:
|
||||
|
||||
1. Make sure that you have [homebrew cask](https://caskroom.github.io/).
|
||||
1. `brew update`
|
||||
1. `cd /usr/local/Homebrew/Library/Taps/caskroom/homebrew-cask/Casks`
|
||||
@ -273,4 +224,4 @@ On macOS:
|
||||
1. `brew cask style --fix ./powershell.rb`, make sure there are no errors
|
||||
1. `brew cask audit --download ./powershell.rb`, make sure there are no errors
|
||||
1. `brew cask reinstall powershell`, make sure that powershell was updates successfully
|
||||
1. Commit your changes, send a PR to https://github.com/caskroom/homebrew-cask
|
||||
1. Commit your changes, send a PR to [homebrew-cask](https://github.com/caskroom/homebrew-cask)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user