Difference between revisions of "Documentation Release Process"

Latest revision as of 16:22, 4 June 2025

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

URLs

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.

Branching Policy

As with development, we maintain two documentation branches, stable and future for whatever the current stable version is (at this writing it's 4.x).

• Documentation updates describing features which are exclusively in code's future branch should be applied only on future.
• All others should be applied on stable and then merged in future.

Check Git#Branching and Merging to see if something changed.

Major Releases

A major release is the first release to bring new development features to the users. This is shown by a jump in the version number (for example from 3.x to 4.0), and signifies the start of a new major development cycle.

git

This means the branches in our repository have to be reshuffled. The release is done from a commit on the future branch. This commit should now become the HEAD commit for the stable branch because maintenance should now happen from there on. At the same time it may be necessary to keep up maintenance to the previous major series, so this should now get its own branch.

 git branch stable-X.Y stable # for example git branch stable-3 stable
 git checkout stable
 git merge --ff-only future

docbook/gnc-docbook.dtd

Update <!ENTITYs vers-unstable ... series-stable.

GnuCash Wiki

This is now done by templates, see Release_Process#Update_Release_Version.

Website

New Main Version only

Create a new directory for the documentation in the website repo:

mkdir v${MainVersion}
git add v${MainVersion}

Checkout release branch

• Determine which branch to do the release from:
  • If you want to release a new maintenance release on the current stable series (like 4.1, 4.2,...) then choose stable
  • If you want to release a new maintenance release on an older stable series (like 3.16 if 4.x is the current stable series) then choose stable-X
  • If you are about to release a development snapshot (like 4.900, 4.901,...), choose future
• 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

Verify future is a superset of stable

If you are about to release from future you should verify that future is a superset of stable. You can do this by running the following command

 git log future..stable

This command should not list any commits. If it does, checkout future and merge stable into it:

 git checkout future
 git merge stable

Note

The same check should be performed when releasing from stable and there is an older stable-X branch on which commits still happen.

Checks and Updates

docbook/gnc-docbookx.dtd

Update <!ENTITYs series-stable, vers-stable, and date. Check also app-fq-vers.

Set <!ENTITY url-docs "&url-docs-release;">

Perhaps reset it to <!ENTITY url-docs "&url-docs-draft;"> after the release is finished?

• In each copy of manual/index.docbook and guide/index.docbook, update the document history.

• Update the copyright - the year might change.
• Check if Authors, Maintainers and Translators from main documents are in sync with
  • AUTHORS
• Check if gnucash/DOCUMENTERS on both development and stable branches is in sync with gnucash-docs/AUTHORS.
• Update the version number in project of CMakeLists.txt.
• Update NEWS by running ../gnucash/util/git-release-notes.pl > release.news and copying over the changes, reformatting appropriately.
• Update the ChangeLog:

 git log --format="%ad %aN %n%n%x09* %s%d%n" --date=short <previous release tag>.. > ChangeLogNew
 mv ChangeLog ChangeLogOld
 cat ChangeLogNew ChangeLogOld > ChangeLog
 rm ChangeLogNew
 rm ChangeLogOld 

• Commit this change as "Release X.X"

Git

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

mkdir build && cd build
cmake ..
make distcheck

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

• Tag the release and push:

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

N.B. If after pushing the tag you discover a problem, fix the problem and release a new version with a 3-part number e.g. 4.10.1.

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 4.5 gnucash-docs-release

• Inside gnucash-docs-release, run

mkdir build && cd build
cmake ..
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.) N.B. If a retag was necessary be sure to modify the tarball name to match so that it the automatic build scripts can find it.

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.

Building these requires the Apache FOP (XML Formatting-objects Processor) for PDF and Calibre for mobi ebooks.

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

cmake --with-mobi ..
make html pdf epub mobi

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

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.

Git housekeeping after a release

If any changes were committed during the release steps above, merge these upwards to the other upstream branches. For example if you committed something to stable, merge stable into future:

 git checkout future
 git merge stable

Expect a merge conflict here for the changed version number. This is normal and the conflict should be resolved by keeping the version number in future. There may be other merge conflicts. Evaluate them and fix them accordingly.

If the release was from an older stable-X.Y branch, merge these changes into stable and then merge stable into future. Expect the same version number conflict during the merges.

The first command creates a maintenance branch for the old stable release series. The subsequent commands move stable to where future is now. If the latter command fails there are commits on the stable branch that didn't get merged into future. This should not happen if the earlier steps were followed to #Verify future is a superset of stable.

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 git, 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, ..., v3, v4, ...). Note that each version directory starts with a lowercase "v" (from "version"). You'll need to make a new one at every major release.

Next, we'll copy all of the alternative documentation formats into the version directory. Run the copy-files.sh script in gnucash-htdocs-docs:

 ./copy-files.sh /absolute/path/to/built documents version

./copy-files.sh /home/foo/gnucash-docs-release/build v5

If that worked well, you can now 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 v5
git rm [deleted files]...
git commit -m "Add documentation for version 5.5 to the GnuCash website"
git push origin <branch>