Difference between revisions of "Documentation Release Process"

From GnuCash
Jump to: navigation, search
(Bugzilla)
(Updates for gnucash-help->gnucash-manual, gnucash-.*.xml->index.docbook.)
 
(75 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This page is intended to gather the steps for a release of the GnuCash documentation. It was animated by [https://bugzilla.gnome.org/show_bug.cgi?id=652350 Bug 652350 - Formalize the Documentation release process] and is partial related to the code [[Release Process]].
+
This page gathers the steps for a release of the GnuCash documentation. It was animated by [https://bugzilla.gnome.org/show_bug.cgi?id=652350 Bug 652350 - Formalize the Documentation release process].
  
'''ATTENTION This is a draft version, cloned from the program's release process and gradually being tailored for the documentation release process'''
+
== URLs ==
 +
{| border="1" cellpadding="5" cellspacing="0" bgcolor="white"
 +
| URL
 +
| Meaning
 +
|-
 +
| ssh://code.gnucash.org/gnucash-docs
 +
| source files of the docs
 +
|-
 +
| ssh://code.gnucash.org/gnucash-htdocs-docs
 +
| ready docs to be presented at ...
 +
|-
 +
| ssh://code.gnucash.org/gnucash-htdocs
 +
| website source files.
 +
|-
 +
|}
 +
== 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 ==
+
== Branching Policy ==
Check the [[Subversion#Current_Backport_Policy]].
+
As with development, we maintain two documentation branches, '''master''' and '''maint''' for whatever the current stable version is (at this writing it's '''4.x''').
 +
* Documentation updates describing features which are ''exclusively in code's master branch'' should be applied only on ''master''.
 +
* All others should be ''applied on maint'' and then ''merged in master''. 
 +
 
 +
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 master branch. This commit should now become the HEAD commit for the maint 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 maint-X.Y maint # for example git branch maint-3 maint
 +
  git checkout maint
 +
  git merge --ff-only master
 +
 
 +
 
 +
;[https://github.com/Gnucash/gnucash-docs/blob/maint/docbook/gnc-docbookx.dtd#L35 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: <syntaxhighlight lang="sh">
 +
mkdir v${MainVersion}
 +
git add v${MainVersion}
 +
</syntaxhighlight>
  
 
== Checkout release branch ==
 
== Checkout release branch ==
 
* Determine which branch to do the release from:
 
* 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 maintenance release on the ''current stable'' series (like 4.1, 4.2,...) then choose '''maint'''
:* 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 maintenance release on an ''older stable'' series (like 3.16 if 4.x is the current stable series) then choose '''maint-X'''
:* If you want to release a new stable version but the stable series is still on trunk, then choose '''trunk'''
+
** If you are about to release a ''development snapshot'' (like 4.900, 4.901,...), choose '''master'''
* Check out the proper gnucash-docs [[Subversion]] branch.
+
* 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
 +
 
 +
If you are about to release from '''master''' you should verify that '''master''' is a ''superset'' of '''maint'''. You can do this by running the following command
 +
  git log master..maint
 +
This command should not list any commits. If it does, checkout '''master''' and merge '''maint''' into it.
 +
  git checkout master
 +
  git merge maint
 +
 
 +
;Note: The same check should be performed when releasing from '''maint''' and there is an older '''maint-X''' branch on which commits still happen.
  
 
== Checks and Updates ==
 
== Checks and Updates ==
  
 +
;[https://github.com/Gnucash/gnucash-docs/blob/maint/docbook/gnc-docbookx.dtd#L33 docbook/gnc-docbookx.dtd]: Update <!ENTITYs <tt>series-stable</tt>, <tt>vers-stable</tt>, and <tt>date</tt>. Check also <tt>[https://github.com/finance-quote/finance-quote/releases app-fq-vers]</tt>.
 +
:Set <syntaxhighlight lang="xml" inline><!ENTITY url-docs "&url-docs-release;"></syntaxhighlight>
 +
:Perhaps reset it to <syntaxhighlight lang="xml" inline><!ENTITY url-docs "&url-docs-draft;"></syntaxhighlight> 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
 
* 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
 
** the related OMF files (has someone expirience with existing tools for this task?) and
 
** AUTHORS  
 
** AUTHORS  
* Check if gnucash/DOCUMENTERS both trunk and stable is in sync with gnucash-docs/AUTHORS.
+
* Check if gnucash/DOCUMENTERS on both development and stable branches is in sync with gnucash-docs/AUTHORS.
* Update NEWS (can we adapt some mechanic from gnucashs Changelog updates?)
+
* Update the '''version''' number in <tt>project</tt> of CMakeLists.txt.
* Update the version number of the <tt>[AM_INIT_AUTOMAKE]</tt> macro in <tt>configure.in</tt>
+
* Update NEWS by running ../gnucash/util/git-release-notes.pl > release.news and copying over the changes, reformatting appropriately.
* Commit this change
+
* 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"
  
== Subversion ==
+
== Git ==
* Verify that the chosen branch can build a distribution tarball, compile, and test it fine:
+
* Verify that the chosen branch can build a distribution tarball, compile, and test it satisfactorily:
  ./autogen.sh
+
  mkdir build && cd build
  ./configure
+
  cmake ..
 
  make distcheck
 
  make distcheck
 
:Fix any errors this step may turn up, commit and check again.
 
:Fix any errors this step may turn up, commit and check again.
* Copy the subversion trunk to the tags/<version-number>. For example:
+
* Tag the release and push:
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"
+
  git tag -am "Release 4.5" 4.5
:Remember to use the proper source branch here!
+
  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 ==
 
== Source tarballs ==
* Checkout the release tag from subversion. '''Do a clean checkout here to avoid packaging unreleased changes !''' For example:
+
* After the tag has propagated, clone your repo to make sure that no stray changes are put in the tarball. For example:
  svn co svn+ssh://svn.gnucash.org/repo/gnucash-docs/tags/2.4.2 v2.4.2
+
  cd ..
* Inside v2.4.2, run
+
rm -rf gnucash-docs-release
./autogen.sh
+
git clone gnucash-docs -b 4.5 gnucash-docs-release
  mkdir build
+
* Inside gnucash-docs-release, run
cd build
+
  mkdir build && cd build
  ../configure
+
  cmake ..
 
  make distcheck
 
  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.
 
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.)
+
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 ==
 
== 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.
 
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 [https://xmlgraphics.apache.org/fop/ Apache FOP (XML Formatting-objects Processor)] for PDF and [http://calibre-ebook.com/ Calibre ] for mobi ebooks.
 +
 
* In the same build directory we created in the previous step, run
 
* In the same build directory we created in the previous step, run
  ../configure --with-mobi
+
  cmake --with-mobi ..
 
  make html pdf epub 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).
+
This should generate the various alternative formats in subdirectories per document (guide or help) and per language (like C, de, 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.
 
  
 
== Sourceforge file uploads ==
 
== Sourceforge file uploads ==
Line 64: Line 134:
 
* Upload the file created above to this directory.
 
* Upload the file created above to this directory.
  
== GnuCash Website ==
+
== Git housekeeping after a release ==
=== 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:
+
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 maint, merge maint into master:
cd gnucash-htdocs/docs
+
  git checkout master
mkdir v2.4
+
  git merge maint
svn ci -m "Create v2.4 documentation directory"
 
cd ../..
 
  
Note that each version directory starts with a lowercase "v" (from "version")
+
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 master. There may be other merge conflicts. Evaluate them and fix them accordingly.
  
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:
+
If the release was from an older maint-X.Y branch, merge these changes into maint and then merge maint into master. Expect the same version number conflict during the merges.
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.
+
The first command creates a maintenance branch for the old stable release series. The subsequent commands move maint to where master is now. If the latter command fails there are commits on the maint branch that didn't get merged into master. This should not happen if the earlier steps were followed to verify ''master'' is a superset of ''maint''.
  
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):
+
== GnuCash Website ==
cd gnucash-htdocs
+
=== Uploading the new documentation versions ===
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 ===
+
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:
* Go to your GnuCash svn source directory
+
* Move one level up from the gnucash-docs-release directory created above
* cd util/svnlog2ul/
+
  git clone ssh://code.gnucash.org/gnucash-htdocs-docs
* 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.
+
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, ...).  
* Go to news in the gnucash-htdocs directory we checked out in the previous step
+
Note that each version directory starts with a lowercase "v" (from "version")
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 ===
+
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/v4"
 +
(cd gnucash-docs-release/build/guide; for i in C de it ja pt; 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 pt; do rsync -av --delete $i/gnucash-manual{,.pdf,.epub,.mobi} $base/$i/;done)
  
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.
+
You should find in the gnucash-htdocs-docs directory a shell script named <tt>copy-files.sh</tt> which does the rsync for you:
 +
  ./copy-files.sh /path/to/build_dir v4
 +
'''N.B.:''' The path must be absolute for it to work correctly.
  
There are two webpages related to the documentation:
+
Note that the commands should be run from the parent directory of gnucash-docs-release and gnucash-htdocs, and the parentheses are important.
* 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:
+
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):
* In docs.phtml
+
cd gnucash-htdocs-docs
** the section Current stable release, should now mention the stable series version (2.4 instead of 2.2)
+
git status
** the documentation for the previous version should be added to the '''Older Documentation section'''.
+
# This will show a list of new/changed/deleted files.
* In viewdoc.phtml
+
git add v4
** the '''$current_stable''' parameter should be updated to reflect the new major version
+
git rm [deleted files]...
** an additional switch-case branch should be added for the new series (in the switch-case-construct used to set $showrev).
+
  git commit -m "Add documentation version 4.5 to the GnuCash website"
 
+
git push origin <branch>
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.
 

Latest revision as of 18:22, 6 April 2023

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

URLs

URL Meaning
ssh://code.gnucash.org/gnucash-docs source files of the docs
ssh://code.gnucash.org/gnucash-htdocs-docs ready docs to be presented at ...
ssh://code.gnucash.org/gnucash-htdocs website source files.

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, master and maint for whatever the current stable version is (at this writing it's 4.x).

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

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 master branch. This commit should now become the HEAD commit for the maint 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 maint-X.Y maint # for example git branch maint-3 maint
 git checkout maint
 git merge --ff-only master


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 maint
    • 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 maint-X
    • If you are about to release a development snapshot (like 4.900, 4.901,...), 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

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

 git log master..maint

This command should not list any commits. If it does, checkout master and merge maint into it.

 git checkout master
 git merge maint
Note
The same check should be performed when releasing from maint and there is an older maint-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
    • the related OMF files (has someone expirience with existing tools for this task?) and
    • 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 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.

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 maint, merge maint into master:

 git checkout master
 git merge maint

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 master. There may be other merge conflicts. Evaluate them and fix them accordingly.

If the release was from an older maint-X.Y branch, merge these changes into maint and then merge maint into master. 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 maint to where master is now. If the latter command fails there are commits on the maint branch that didn't get merged into master. This should not happen if the earlier steps were followed to verify master is a superset of maint.

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")

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/v4"
(cd gnucash-docs-release/build/guide; for i in C de it ja pt; 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 pt; do rsync -av --delete $i/gnucash-manual{,.pdf,.epub,.mobi} $base/$i/;done)

You should find in the gnucash-htdocs-docs directory a shell script named copy-files.sh which does the rsync for you:

 ./copy-files.sh /path/to/build_dir v4

N.B.: The path must be absolute for it to work correctly.

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 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 v4
git rm [deleted files]...
git commit -m "Add documentation version 4.5 to the GnuCash website"
git push origin <branch>