Difference between revisions of "Release Process"

Revision as of 23:58, 28 January 2014

Each GnuCash release involves a number of steps for the release manager. This page is intended to gather these steps for the program, while the Documentation Release Process is separated.

Backport Policy

Check the Git#Current_Backport_Policy.

Git Based Release

These steps detail how to perform a GnuCash release from a GnuCash git repository. This is only possible from 2.5.2 and up. For older releases check out the #Svn Based Release steps below.

Notes

• While writing this svn is still the canonical repository for the GnuCash code. This affects the way releases are tagged. So even though we start from a git repo the full release process requires a few svn related commands to be executed. These are marked with SVN-MASTER in the process description below. Once we fully switch to a git primary repository these commands will be replaced with equivalent git commands. For reference these are already added in the process below, prefixed with GIT-MASTER. These should not be used yet ! We expect to switch the primary repositories to git around the time we will release GnuCash 2.6.
• Where relevant, the process below assumes that the primary git repository is configured as a remote called "upstream". If you have configured it under another name, please adapt the commands below accordingly.
• Svn and git use a different default branch. If svn is the primary repository the default branch is trunk. If git is the primary repository the default branch is master. The commands below will reflect this.

Source preparation

• Check out Git branch you wish to release. For example

SVN-MASTER

git checkout trunk
git-update

GIT-MASTER

git checkout master
git pull --rebase

• Verify that current branch can build a distribution tarball, compile, and test it fine:

make distcheck

In this step, some files might have been changed such as POTFILES.in, which can then be committed before actually incrementing the version number. However, some of the test data files might also have been changed due to "make check", but those changes should not be committed.

• Update the version number of the [AC_INIT] macro in configure.ac
• Run

  util/gitlog2ul.sh <previous release> > release.News

and summarize significant changes in a release summary in NEWS.

• If this is the first release of a calendar year, copy ChangeLog to ChangeLog.YYYY with YYYY being the previous year.
• Find the rule in Makefile.am to generate the ChangeLog, update the "--since" parameter to the start of the current year.
• Run make, which should update the ChangeLog file now.
• If you are building out of tree, copy the updated ChangeLog from your build directory to your source directory.
• Commit changes to NEWS and the ChangeLogs to the git repository. Don't forget to add the new ChangeLogs first if it's the start of a new year.
• Push all your changes to upstream:

SVN-MASTER

git svn dcommit

'GIT-MASTER

git push upstream master:master

• Tag the new release.

SVN-MASTER This is done by copying trunk to tags/<version-number> in the subversion repository. For example:

svn cp svn+ssh://svn.gnucash.org/repo/gnucash/trunk svn+ssh://svn.gnucash.org/repo/gnucash/tags/2.5.2 -m "Tag 2.5.2"

GIT-MASTER For example:

git tag 2.5.2 -m "Tag 2.5.2"
git push upstream --tags

FIXME Does git tagging require more options ?

• SVN-MASTER Get the latest tag in your local git repository:

 git checkout trunk
 git-update
 git fetch -t

Source tarballs

• Checkout the release tag from git. Clone your git repo here to avoid packaging unreleased changes ! For example:

git clone <your-local-up-to-date-git-repo> r2.5.2
cd r2.5.2
git checkout 2.5.2

• Inside r2.5.2, run

./autogen.sh
mkdir build
cd build
../configure
make distcheck
sha256sum gnucash-2.5.2.tar.* > README

This should generate two tarballs, one bzip2 compressed and one gzip compressed, along with a README file containing the sha256 hashes. Using make distcheck performs several checks on the distribution before making the tarballs, then decompresses one of them, builds it, and runs make check on the results which ensures that everything is properly packaged for distribution.

A user pointed out on IRC that SourceForge not only doesn't use https but also generally redirects the user to a third-party mirror to provide the download. He was concerned that an attack is possible in that insecure environment. Accordingly, we also make checksums and put them in the README so that SourceForge will display them on the download page. By using a build directory you avoid overwriting the source README.

Documentation

Now make a documentation release using the same version number as you set above for GnuCash. See Documentation Release Process for the procedure.

Windows Executable

The creation of the tag in the first section will automatically trigger the build for the Windows Executable in the next nightly build. The resulting executable can be downloaded the day after from http://code.gnucash.org/builds/win32

Mac OS X Executable

This package is usually created by John Ralls using this procedure .

Sourceforge file uploads

All the above build targets should be uploaded to Source Forge.

• Log in on the [Source Forge GnuCash website]
• Go to the Project Admin -> File Manager section
• Create a new directory for the release, either under gnucash (stable) or gnucash (unstable)
• Upload the files created above to this directory.
• If this release is the latest stable release, mark these files as the default download targets for their respective platforms (.exe file on Windows, .dmg file on Mac OS X, source tarball on all other targets).

GnuCash Website

Note that gnucash-htdocs is a pure git repository. In order to update the website you will hence have to follow the instructions on our Git wiki page to prepare a local gnucash-htdocs repository with commit access to the primary repository on code.gnucash.org. Be sure to follow the committer instructions for pure git repositories on that page !

Adding the announcement text

• Go to your GnuCash git source directory
• Run the 'gitlog2ul.sh' utility to get the commit messages relevant to this release. For example:

./util/gitlog2ul.sh 2.5.1 2.5.2 > 2.5.2-commits.html

• Do the same in the gnucash-docs, using gnucash/utils/gitlog2ul.sh.

Use the output together with a previous news file to generate a news message for this release. The easiest way is probably to copy the old news file into a new one, replace all occurrences of the old release number with the new release number and then insert the list of commits.

• Go to your gnucash-htdocs git directory
• Checkout the master branch and make sure it's up to date

cd gnucash-htdocs.git
git checkout master
git pull upstream

• Go to the news files

cd news

• Copy the last release newsfile. The filename format is usually YYMMDD-<releasenumber>.news. For example:

cp 130430-2.5.1.news 130527-2.5.2.news

• Replace the old release numbers in this file. Note that release announcements usually contain two release numbers: the current release and the previous release. Both of them should obviously be replaced. The order to execute the following commands is important ! For example:

sed -i -e 's/2.5.1/2.5.2/g' 130527-2.5.2.news
sed -i -e 's/2.5.0/2.5.1/g' 130527-2.5.2.news

• Now open the file in your favourite editor and replace the changes with the commit messages you had just created. You will have to manually bring some order in the commits (for example, put the commits that fix bugs together in one group, other user visible changes in another group and internal changes in still another one)
• Add the new file to revision control

git add 130527-2.5.2.news

Updating the release number for the download pointers

Next, the release number should be added to the website configuration script. This ensures all download links are appropriately updated.

• Edit the file gnucash-htdocs/externals/global_params.php. The first few lines in this script set various release numbers: latest_stable, latest_unstable and variants thereof on Windows and MacOS X. Adapt these parameters as needed.

Finally, all these changes to the website should be committed. From the base directory:

git add <changed-files>
git commit -m "Update to release x.y.z"
git push upstream master:master

The last command will take care of updating the live website.

Mailing list announcement

Send the same announcement to the following lists:

• gnucash-devel@gnucash.org
• gnucash-user@gnucash.org
• gnucash-announce@gnucash.org

To do so, you have to be subscribed to the mailing lists. Then I found it easiest to copy the release announcement from my web browser into a new mail message (Kmail). In kmail this converts the html in a reasonably clean plain-text message. Some further minor cleanup may be necessary.

Bugzilla

After logging in

• Add the new version number and eventually
• add the next milestone.

Release Schedule

Add the actual release date to Release Schedule.