Documentation Release Process

From GnuCash
Revision as of 18:05, 23 November 2013 by Jralls (talk | contribs) (→‎Backport Policy: Replace Git with Subversion)
Jump to: navigation, search

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 and is partial related to the code Release Process.

ATTENTION This is a draft version, cloned from the program's release process and gradually being tailored for the documentation release process

Backport Policy

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 trunk
  • 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.4
  • If you want to release a new stable version but the stable series is still on trunk, then choose trunk
  • Check out the proper gnucash-docs Subversion branch.

Checks and Updates

  • 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 NEWS (can we adapt some mechanic from gnucashs Changelog updates?)
  • Update the version number of the [AM_INIT_AUTOMAKE] macro in configure.in
  • Commit this change

Subversion

  • Verify that the chosen branch can build a distribution tarball, compile, and test it fine:
./autogen.sh
./configure
make distcheck
Fix any errors this step may turn up, commit and check again.
  • Copy the subversion trunk to the tags/<version-number>. For example:
svn cp svn+ssh://svn.gnucash.org/repo/gnucash-docs/trunk svn+ssh://svn.gnucash.org/repo/gnucash-docs/tags/2.4.2 -m "Tag 2.4.2"
Remember to use the proper source branch here!

Source tarballs

  • Checkout the release tag from subversion. Do a clean checkout here to avoid packaging unreleased changes ! For example:
svn co svn+ssh://svn.gnucash.org/repo/gnucash-docs/tags/2.4.2 v2.4.2
  • Inside v2.4.2, 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_DE, it_IT and so on).

FIXME The standard setup will refuse to build a Japanese pdf due to missing fonts. To build the Japanese pdf, additional fonts have to be installed and fop-ttfreader must be present. I didn't manage to set this up properly on a Fedora 16 system.

Re: While Adobe offers japanese fonts, they are not free. So we use the fonts published by the Infomation-technology Promotion Agency ipa.go.jp. - Don't mess with "International Phonetic Aphabet" as offered e.g. by SIL! - Debian based distros have a package ttf-ipafont. Others can download them from http://en.sourceforge.jp/projects/ipafonts/ .
Probably this section should become part of the Readme?

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 v2.4.2 directory created above
svn co svn+ssh://svn.gnucash.org/repo/htdocs/trunk gnucash-htdocs

You should now have the v2.4.2 and gnucash-htdocs directories next to each other. Inside the htdocs directory you will find a subdirectory docs and in there a subdirectory per major release (1.8, 2.0, 2.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
mkdir v2.4
svn ci -m "Create v2.4 documentation directory"
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
(cd v2.4.2/build/guide; for i in C de_DE it_IT ja_JP; do rsync -av --delete $i/gnucash-guide{,.pdf,.epub,.mobi} $base/gnucash-htdocs/docs/v2.4/$i/;done)
(cd v2.4.2/help; for i in C de_DE it_IT; do rsync -av --delete $i/gnucash-help{,.pdf,.epub,.mobi} $base/gnucash-htdocs/docs/v2.4/$i/;done)

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

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

cd gnucash-htdocs
svn stat
# This will show a list of new/changed/deleted files.
svn add [new files]...
svn rm [deleted files]...
svn ci -m "Add documentation version 2.4.2 to the GnuCash website"

Adding the announcement text

  • Go to your GnuCash svn source directory
  • cd util/svnlog2ul/
  • Run the 'svnlog2ul.sh' utility to get the commit messages relevant to this release. For example:
./svnlog2ul.sh 2.3.9 2.3.10 > 2.3.10-commits.html

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 newsfile 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 news in the gnucash-htdocs directory we checked out in the previous step
cd gnucash-htdocs/news
  • Copy the last documentation release newsfile. The filename format is usually YYMMDD-docs-<releasenumber>.news. For example:
svn cp 110702-docs-2.4.1.news 121118-docs-2.4.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.4.1/2.4.2/g' 121118-docs-2.4.2.news
sed -i -e 's/2.3.16/2.4.1/g' 121118-docs-2.4.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)

Updating the release number for the download pointers

If this was a minor release (meaning, you didn't have to create a new version's directory in docs), you can skip to the end of this section to check in the website changes. Otherwise, you may need some extra work.

There are two webpages related to the documentation:

  • docs.phtml: on this page a user can choose a document to read or download for a certain version or language.
  • viewdoc.phtml: this page is loaded whenever the user clicks on a link to view the documentation online.

If this is a major documentation release (for example the previous documentation was v2.2.x and the new is v2.4.0), both pages have to be altered:

  • In docs.phtml
    • the section Current stable release, should now mention the stable series version (2.4 instead of 2.2)
    • the documentation for the previous version should be added to the Older Documentation section.
  • In viewdoc.phtml
    • the $current_stable parameter should be updated to reflect the new major version
    • an additional switch-case branch should be added for the new series (in the switch-case-construct used to set $showrev).

In both cases, use the existing code as an example to make the necessary changes. It is probably mostly a matter of copy and paste, and changing the proper version markers.

Finally, all these changes to the website should be committed. 

svn ci -m "Update to release x.y.z"

The commit 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.

Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Documentation_Release_Process&oldid=10587"