Building a Release

These notes document the process for building a planned release of NuPattern. (updated as of version: 1.4.24.0)

This process is expected to be executed by a project coordinator/developer, working with The Outercurve Foundation who provide the signing services for assemblies, and VSIXes and MSIs.
The OCF contact for signing is currently Eric Schultz (wwahammy@hotmail.com).
The signing process is fully automated,and implemented in MSBUILD scripts.

The release process delivers a set of binary assets (VSIXes, MSI, Documents etc.) that are then posted on this project site as a 'Release' containing downloads and information.

Versioning the Codebase

The outcome of this section is:

A incremented version in the codebase

Overview

The version number of NuPattern is controlled centrally in a single file, and all code and deployable assets in the codebase use this version number for each release.
The version number for each release must be incremented.

While much of the of the code and many of the assets in the codebase and deliverables are updated automatically as part of every build, some assets still require updating manually.

To complete this process, please follow the instructions detailed in the
Version Releases page.

Once the codebase version number has been incremented, you can proceed to building and signing the binaries.

Building the Binary Assets

The outcomes of this section are:

An authenticode signed Authoring VSIX

An authenticode signed HOL VSIX

An authenticode signed MSI

Note: all VSIXes contain assemblies which are themselves both strong-name signed and authenticode signed.
Note: all VSIXes and MSI are authenticode signed.

Overview

A delivered and signed VSIX or MSI contains a number of assemblies and other VSIXes which are themselves signed.

Similar to a russian doll, a VSIX will be created from nested parts (i.e. Assemblies and VSIXes), where each nested part will require signing. This makes the process of signing a deliverable VSIX a muti-stage signing process. Requiring several signing and repackaging
passes.

All VSIXes contain at least 1 NuPattern assembly, which must be strong-name signed first. But all assemblies from all VSIXes can be signed in one pass. They are strong-named signed and then authenticode signed.

The child nested VSIXes are then upgraded with the signed assemblies, and then authenticode signed themselves, in the next pass.

The nesting (parent) VSIXes are then upgraded with the signed child VSIXes, and then signed themselves, in the next pass.

Finally, the MSI is rebuilt with all the signed VSIXes, and then authenticode signed.

In addition to signing VSIXes, VSIXes are also recompressed as ZIP files with the highest compression ratio to minimize file size. We use additional MSBUILD targets and tasks in NuPattern.Build.Tasks.dll to achieve the maximum zip compression ratio.

Process Overview

This process is fully automated by a number of MSBUILD scripts and targets which can be used in an automated build. Or easily invoked manually by a batch script in the 'Src\Release\' folder.

In either case, the signing service which is provided by the Outercurve Foundation requires that does the actual signing of the artifacts requires access using a authorized account. The credentials used for access must be provided to the MSBUILD scripts in
some way.
The credentials cannot be published publically, or reside in artifacts in the source tree.

To run the MSBUILD scripts from an automated build server (i.e. teamcity.codebetter), the credentials can be defined in the build configuration, for the properties: $(SignUserName) and $(SignUserPassword).

To run the MSBUILD scripts from the batch file in the 'Src\Release' folder, the credentials must be provided manually in the console window when prompted for by the batch file.

The automated process: builds all solutions in both VS2010 and VS2012 flavors, then signs all assemblies in all the built VSIXes. Repackages the signed assemblies into the VSIXes, signs those VSIXes, repackages those VSIXes into their containing VSIXes, signs
those containing VSIXes, then rebuilds the MSI installer, and finally signs the installer.

Once the automated process is complete, the signed MSI installer and signed VSIXes can all be found in the 'Src\Release\Processed\Signed' folders.