This document describes how Noda Time is released. It is intended to be used as a checklist by the person doing a release.
Note that we should not build releases on Mono at present, since the resulting IL triggers a bug in the .NET 4 64-bit CLR (see the building and testing section in the developer guide).
When everybody's happy, there are no issues outstanding for the milestone, and all the tests pass.
Search the issue tracker for open issues with the right milestone (e.g.
is:open is:issue milestone:1.4.0).
Update to the candidate revision (probably HEAD) of the correct branch (e.g.
1.0.x) and build and run all the tests as normal. The build
and test steps should pass on Visual Studio 2015 and at least one supported
OS/version combination for Mono (i.e. 'Mono 2.10.9 on Linux').
If necessary, update the version of tzdb on the branch to the latest current version, following the instructions in the "Updating the time zone database" section in the user guide.
Before building the first release with a given minor version number (i.e. 1.0.0, 1.1.0, or more typically, a -beta or -rc version of the same), we'll need to branch. New user-visible functionality is introduced with a new minor version number (per the Semantic versioning spec).
The branching model used by Noda Time is the Subversion-style backport model. In brief:
Note the difference between the format of names used for tags ('1.0.0-beta2', '1.0.0') and those used for branches ('1.0.x'). Git will allow both to be used as "tree-ish" values, so it is important that they do not collide.
The only change that needs to be made to the branch after creation is to
<Preliminary/> tag from the Sandcastle project file; see e.g.
If this release required the creation of a new branch, then the following files
master branch should be updated to bump (at least) the minor version
version), per the following scheme:
Suppose we were building version 1.2.3-beta4, then:
- In the NuGet package specs,
<version>should contain the version number ('1.2.3-beta4'). The
NodaTime.Testing.nuspecshould reference the initial release for the major/minor version (i.e. '1.2.0') for stable versions, or the full version for pre-release versions.
- In the AssemblyInfo files,
AssemblyVersionshould be set to just the major/minor version ('1.2').
AssemblyFileVersionshould be set to the major, minor, and patch version ('1.2.3'), and
AssemblyInformationalVersionshould be set to the version number ('1.2.3-beta4'). (See this Stack Overflow post for more information about how these are used.)
Update the version number by building the tools solution and then running the
msbuild build\Tools.sln build\SetVersion\bin\Debug\SetVersion.exe 1.1.0-dev
The version number string should be of the form
Switch to the correct branch (e.g.
Update the version number according to the scheme above by building the tools
solution and then running the
msbuild tools\Tools.sln build\SetVersion\bin\Debug\SetVersion.exe 1.2.3-beta4
This will update the following AssemblyInfo files and NuGet package specs to include the version number you are building:
Add the current date and TZDB version to the version history in
www/unstable/userguide/versions.md and regenerate all documentation.
(The branch version of the
www/ directory is only used for the offline
user guide; we leave the documentation in
unstable/ for branches.)
Commit the above, then tag that commit:
git tag 1.0.0-beta1
(If the tag has already been applied, use
-f to force it.)
Switch back to the master branch and update the version history in that branch
to match the changes applied to the release branch, then (if this release
changes the latest stable release), update the date and version number of the
latest stable version in
www/_config.yml, and (if that new stable release is
not a patch release), also update the
/userguide redirects in
Push these changes to GitHub, ensuring that you push the tags as well as any changes.
--tags from the command line.)
First, create a new clone for building the release. Doing this avoids the need to worry about ignored files and local changes making their way into the archives.
Copy the Noda Time private key into the top-level directory.
build\buildrelease.bat batch file to build all the release artifacts:
cd build buildrelease 1.0.0-beta1
This will create:
buildrelease.bat for details.)
Upload the source and release zipfiles to the project website, under
downloads directory. To do this, pull the
downloads directory accordingly, commit and then push back
up to GitHub. The web site will update automatically.
downloads/index.html file to include the new downloads,
including SHA-256 hash.
If this is a stable release, update the version number and the links on the front page to point to the new downloads.
Upload the three NuGet packages to nuget.org:
nuget push NodaTime.1.0.0-beta1.nupkg nuget push NodaTime.Testing.1.0.0-beta1.nupkg nuget push NodaTime.Serialization.JsonNet.1.0.0-beta1.nupkg
Copy the generated API documentation from
docs/api to the corresponding
/$BRANCH/api directory in the
Post to the mailing list, blog, etc.
If this release was a stable release, then the generated XML documentation
should be copied to
data/versionxml/ on the master branch.
If this release required the creation of a new branch, then the following updates need to be made to the master branch for the website:
www/unstable/userguideshould be copied to
versions.md, which should come from the branch copy)
www/_layouts/foundation.html) should be adjusted to add the new branch for the "API" and "User Guide" dropdowns