Win7/PowerShell7
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update the releasing documentation to reflect the desired release steps and order (#3938)

Browse Source 
* 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 2017-06-06 17:59:40 -07:00 committed by Mike Richmond
parent 9eed401427
commit 7681fe9585
2 changed files with 117 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.spelling
View File

@ -296,6 +296,11 @@ vors
- docs/maintainers/releasing.md
2012r2
CHANGELOG.md
Dockerfiles
downlevel
Effing
PowerShellCore
Ronn
Toolset
v6
WiX

265
docs/maintainers/releasing.md
View File

@ -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
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
On macOS or a supported Linux distro, run the following commands:
```powershell
Import-Module .\build.psm1
# 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
# 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
# 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:
## NuGet Packages
In the `release` branch, 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]
# 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)