Difference between revisions of "Documentation Release Process"

Revision as of 21:10, 28 September 2014

This page is intended to gather the steps for a release of the GnuCash documentation. It was animated by Bug 652350 - Formalize the Documentation release process.

Releases

Beginning with 2.6.0, documentation releases should be done at the same time as GnuCash releases, with the Documentation release number corresponding to the GnuCash release. Do this even if there are no significant documentation changes in order to keep the numbers synchronized.

Backport Policy

As with development, we maintain two documentation branches, master and whatever the current stable version is (at this writing it's 2.6) except for the three months immediately after a new series is released when development is focussed on fixing the bugs found as the new code first encounters a large number of users. When a stable branch exists and a change is relevant to both, make the change in both branches. If the text surrounding the change is the same in both, you may be able to use git cherry-pick to apply the same commit to both braches.

If there is a separate stable branch check the Git#Current_Backport_Policy.

Checkout release branch

• Determine which branch to do the release from:

• If you are about to release a development snapshot, choose master
• If you want to release a new stable version and the stable series is already on its own branch, then choose that stable branch, eg. 2.6
• If you want to release a new stable version but the stable series is still on master, then choose master

• Clone gnucash-docs if you don't already have one.

 git clone ssh://code.gnucash.org/gnucash-docs

• Check out the branch you want and make sure that it's up-to-date:

 cd gnucash-docs
 git checkout <branch>
 git pull --rebase

Checks and Updates

• In each copy of gnucash-help.xml and gnucash-guide.xml, update the document history and version numbers.

• Update the copyright - the year might change.
• Check if Authors, Maintainers and Translators from main documents are in sync with
  • the related OMF files (has someone expirience with existing tools for this task?) and
  • AUTHORS
• Check if gnucash/DOCUMENTERS both trunk and stable is in sync with gnucash-docs/AUTHORS.
• Update the version number of the [AC_INIT] macro in configure.ac
• Update NEWS by running ../gnucash/util/gitlog2ul <previous version> > release.news and copying over the changes, reformatting appropriately.
• Commit this change

Git

• Verify that the chosen branch can build a distribution tarball, compile, and test it satisfactorily:

./autogen.sh
./configure
make distcheck

Fix any errors this step may turn up, commit and check again.

• Tag the release and push:

 git tag -am "Release 2.6.2" 2.6.2
 git push --tags origin <branch>

Source tarballs

• After the tag has propagated, clone your repo to make sure that no stray changes are put in the tarball. For example:

cd ..
rm -rf gnucash-docs-release 
git clone gnucash-docs -b 2.6 gnucash-docs-release

• Inside gnucash-docs-dist, run

./autogen.sh
mkdir build
cd build
../configure
make distcheck

Note that the build is done in a subdirectory here. This is not strictly necessary, but it will simplify some of the future steps in the documentation release process.

The above commands should generate a gzip compressed tarball in the build directory. (Using "make distcheck" instead of only "make dist" does not only create the tarball, but also runs a complete compilation run on the created tarball so that missing files are discovered immediately.)

Other documentation formats

Next to source tarballs, GnuCash also offers the documentation in several other formats for on-line or off-line reading. Currently these formats are html, pdf, epub and mobi.

• In the same build directory we created in the previous step, run

../configure --with-mobi
make html pdf epub mobi

This should generate the various alternative formats in subdirectories per document (guide or help) and per language (like C, de, it and so on).

Sourceforge file uploads

The tarball generated above 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 under gnucash-docs
• Upload the file created above to this directory.

GnuCash Website

Uploading the new documentation versions

The additional documentation formats have to be uploaded to the gnucash website. The website is also managed in subversion, so to get the documentation in there, the current website sources have to be checked out:

• Move one level up from the gnucash-docs-release directory created above

 git clone ssh://code.gnucash.org/gnucash-htdocs-docs

You should now have the gnucash-docs-release and gnucash-htdocs-docs directories next to each other. Inside the htdocs-docs directory you will find a subdirectory docs and in there a subdirectory per major release (v1.8, v2.0, v2.2,...). If no directory exists yet for the major version of the documentation you about to release, then first create this directory and check it in, for example:

cd gnucash-htdocs-docs/docs
mkdir v2.8
cd ../..

Note that each version directory starts with a lowercase "v" (from "version")

Next, we'll copy all of the alternative documentation formats into the version directory. The most efficient way is by using rsync. These commands accomplish this:

base="$PWD/gnucash-htdocs-docs/v2.6"
(cd gnucash-docs-release/build/guide; for i in C de it ja; do rsync -av --delete $i/gnucash-guide{,.pdf,.epub,.mobi} $base/$i/;done)
(cd gnucash-docs-release/build/help; for i in C de it; do rsync -av --delete $i/gnucash-help{,.pdf,.epub,.mobi} $base/$i/;done)

Note that the commands should be run from the parent directory of gnucash-docs-release and gnucash-htdocs, and the parentheses are important.

If that worked well, you can no go into the gnucash-htdocs-docs directory and use git add to add new files and git rm to remove deleted files from the repository (if any):

cd gnucash-htdocs-docs
git status
# This will show a list of new/changed/deleted files.
git add v2.6
git rm [deleted files]...
git commit -m "Add documentation version 2.6.2 to the GnuCash website"
git push origin <branch>

Now return to Release Process for the procedure for making the announcement.