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.
- 1 Commit Policy
- 2 Release Process
- 3 Windows Executable
- 4 MacOS Executable
- 5 Sourceforge file uploads
- 6 Flathub package
- 7 Git housekeeping after a release
- 8 GnuCash Website
- 9 GitHub
- 10 GnuCash Wiki
- 11 Mailing list announcement
- 12 Translation Project
- 13 IRC
- 14 Bugzilla
- 15 Promotion
- 16 New Major/Minor Version
- 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.
- Check out Git branch you wish to release. Typical candidates are master, maint or any maint-X.Y. For example
git checkout master git pull --rebase
- Check translations at the Translation Project Gnucash page for updates and
- apply any that haven't been already committed, e.g. as suggested in translationprojects maintainers page.
- The translation project recommends using
rsync -Lrtvz translationproject.org::tp/latest/gnucash/ po
- But that will replace newer translations from direct contributors with old translations no longer supported by the translation project.
- Another approach is to substituting the last version of GnuCash for '2.6.4'. This does the same except that the old translations have been msgmerged with the last release's pot file making them appear newer than they are.
for i in az ca cs da eu fa ja nl rw sk sr sv tr uk zh_CN; do wget -O $i.po https://translationproject.org/PO-files/$i/gnucash-2.6.4.$i.po; done
- The safest approach is to look at TP Latest and download only the files which have updates since the previous release; for extra confidence examine the "PO Revision Date" header in each file; it should change if there are real translation updates.
- How about using method 3 for the release notes, but get also the merged-only files for statistical purpopse? msgfmt --statistics would else deliver wrong results.
- The translation project recommends using
- Next, check syntax and get the statistics:
cd po for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done
- Check the new files from TP for common mistakes from Translation#Committers.
- These should probably applied to the oldest branch for which you expect do do releases still which may not be the branch you want to release now from. If this is the case apply them to the proper branch (eg maint) and merge upwards to your branch (eg master).
- apply any that haven't been already committed, e.g. as suggested in translationprojects maintainers page.
- 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 This command should not list any commits. If it does, checkout master and merge maint into it
git log master..maint
git checkout master git merge maint
- The same check should be performed when releasing from maint and there is an older maint-X.Y branch on which commits still happen.
- Verify that current branch can build a distribution tarball, compile, and test it fine:
cd .build cmake .. make 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 project(gnucash VERSION) in the root CMakeLists.txt.
- Run to extract the bugs fixed and other changes. There are plain text and HTML sections for the NEWS file and for the web page, Github, and email announcements. The bug list can be copied in to each as-is, the other section should be copied and then edited to leave only changes that impact users or contributors. Translation updates should be removed and the languages updated listed separately.
util/git-release-notes.pl > release.News
- If this is the first release of a calendar year:
- copy ChangeLog to ChangeLog.YYYY with YYYY being the previous year.
- In the root CMakeLists.txt:
- Add ChangeLog.YYYY to the gnucash_DOCS variable,
- Find the rule 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:
git push upstream master:master
- Tag the new release.
- For example:
git tag -am "Tag 3.4" 3.4
Don't push the tag yet! Releases should be atomic, so proceed to building the tarballs and distribution bundles and preparing the release notes and announcements. Push the tag immediately before publishing the release. If for any reason while building tarballs you discover a problem that needs fixing, or if someone pushes a commit that you want to add to the release, you can simply re-tag the release (
git tag -afm "Tag 3.4" 3.4) to the latest commit and make new tarballs and bundles, but you can do that only if you haven't pushed the tag.
- Checkout the release tag from git. Either clone or clean your git repo here to avoid packaging unreleased changes ! For example:
git clone <your-local-up-to-date-git-repo> gnucash-3.0 cd gnucash-3.0 git checkout 3.0
or, while inside your local repo
git clean -fdx
Warning: As Eclipse user do not use the -x flag or all project information will be lost. Or add -e /.project -e /.cproject -e /.autotools -e /.settings/
- Now run
mkdir .build && cd .build cmake .. ninja && ninja distcheck
This should generate two tarballs, one bzip2 compressed and one gzip compressed. Using ninja distcheck performs several checks on the distribution before making the tarballs, then decompresses one of them, builds it, and runs ninja check on the results which ensures that everything is properly packaged for distribution. If you used your regular repo you'll want to clean it again after uploading the tarballs.
Now make a documentation release using the same version number as you set above for GnuCash. See Documentation Release Process for the procedure.
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.
- Perl version
- Check http://strawberryperl.com/ for the recommended version and update strVersion in extra_dist/getperl.vbs.
- From PR#15
- Innosetup version
- Check http://www.jrsoftware.org/isdl.php for updates.
- Can we drop custom language files, because they have become official?
- Are there updates for unofficial translations?
Sourceforge file uploads
All the above build targets should be uploaded to Source Forge.
- Make SHA256 digests of the two tarballs and the three installer packages, e.g.
sha256sum gnucash-*.tar.* > README.sha sha256sum Gnucash*.dmg >> README.sha sha256sum gnucash*.setup.exe >> README.sha
- 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). Mark it "staged" in either the creation or the info dialog.
- Upload the files created above to this directory.
- If this release is the latest stable release, edit each file's metadata by clicking on the 'i' button. For each file indicate for which platforms the file is intended (.exe file on Windows, .dmg file on Mac OS X, source tarball on all other targets). Sourceforge will use this additional information to present a direct download link to the latest release on the user's native platform.
- When everything is ready, open the info dialog for the containing directory and clear the staged check-box. Note that if the release runs into problems that take more than 3 days you may need to renew the "staged" flag.
Steps to run in a clone of Gnucash's gnucash-on-flatpak repo
- Follow https://github.com/Gnucash/gnucash-on-flatpak/blob/master/README.md to set up a gnucash-on-flatpak build environment.
- For stable releases use the master branch; for unstable releases use the unstable branch.
- Do a release build in that build environment by running "build-package.sh -r4.1 -c4.1 -d4.1" (+1 of course)
- The -r parameter stands for revision. It's the primary parameter to tell the build script what to build and can be any single git revision specifier, like a branch, commit hash or tag. In the context of a release, only the tag format should be used. That will trigger a different build procedure than a branch or commit hash: in that case the build procedure will download tarballs from sourceforge for the flatpak generation instead of cloning git repositories.
- The parameters -c and -d also only make sense for release builds and are only required when the tags for code and documentation differ from the sourceforge file directory. In that case set -r to whatever the sourceforge directory name is for the release tarballs (for example 3.8), -c to the code tag to use (for example 3.8b) and -d to the documentation tag to use (for example 3.8). You can omit -c or -d if they are the same as -r, but always specify at least -r (as that will otherwise default to maint resulting in a development build or a tarball not found error).
- The release build will generate/update 3 files in the base directory of the gnucash-on-flatpak repository
Steps to run in a clone of flathub's org.gnucash.GnuCash repo
- Clone https://github.com/flathub/org.gnucash.GnuCash/
- For stable releases use the master branch. For unstable releases use the beta branch.
- Copy the above three files to this clone and commit as "Update to upstream gnucash x.y"
- Run command
git log --date=short --format="<li>%ad - %s (%an)</li>" 3.8-10..HEAD. 3.8-10 should be replaced with the most recent tag in the flathub repo.
- Use the result of this command to update gnucash.releases.xml
- For a fresh release the releases file should be reduced back to only one release. It tracks changes made to the flatpak that are outside of the gnucash release cadence (like rebuilding with a newer aqbanking version). If this is a rebuild due to an updated dependency, add an additional release instead.
- Open file org.gnucash.GnuCash.json and edit the build rule for gnucash. In particular update the GNUCASH_BUILD_ID number to reflect the current version.
- For a fresh release the build id is just "Flathub <release.number>". However as mentioned before the flatpak may be updated more frequently than gnucash itself. In that case the build id would become "Flathub <release.number-pkgnumber>", where the number is obtained by running
git describe --match <release.number>(note the absence of pkgnumber here) without the commit hash.
- Commit gnucash.releases.xml and org.gnucash.GnuCash.json as "Package gnucash <release.number-pkgnumber>" with or without -pkgnumber depending on whether it's a fresh gnucash release or not.
- Tag this commit using
git tag -a -m "Package gnucash <release.number-pkgnumber>" <release.number-pkgnumber>. Again with or without -pkgnumber depending on whether it's a fresh gnucash release or not.
- Push all of this upstream.
From there on you can follow the flathub build process here:
- Stable releases
- Unstable releases
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 merge conflicts here for the changed version number and the different documentation links in README. 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.
A major release
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 2.6.x to 2.8.0), and signifies the start of a new major development cycle.
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-2.6 maint git checkout maint git merge --ff-only master
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.
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
- 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
- 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
- Open the new file in your favorite editor. Using the NEWS files you created for GnuCash and GnuCash Documentation as a basis, revise the announcement to reflect the changes in this new release. Check for
- Announce of Feature/String Freeze for the next release
- This will help to polish the GUI and review for I18N issues.
- Declare start/continuation of Feature/String Freeze for this release
- This will give translators time to complete.
- Add the new file to revision control
git add 130527-2.5.2.news
Updating the release number for the download pointers
After processing #New Major Release, 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. Adapt these parameters as needed.
First Release of the Year
Update the copyright end date in externals/footer.html.
New Major Release
- Copy "Last version for <OS><Version>" elements from
<div id="previous" …>to
<div id="historical" …>and replace there then "$old_stable*" by "$last_*" variables. On demand create them in externals/global_params.php.
- needs a new section in $older<n> as long as we do not convert it in a loop with version dependend LANGs.
- needs adjustemt in
# Parse requested version
Disallow: /docs/v<ancestor(4)> /
Commit the changes.
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.
Set up a new release on GitHub:
- Go to The GnuCash releases page and press the "Create New Release" button.
- Enter the release tag in the tag box. It should already exist.
- Type the title "GnuCash <releasenumber>" into the title box, substituting the correct release version.
- Copy the release news file from "The GnuCash Development Team proudly announces" through the Documentation section and paste it into the "write" box. Use the Preview tab to check the result.
- Drag or select the Mac and Windows installers into the binaries box.
- Click the Publish Release button when everything is ready.
N.B.: This may not work on some browsers or with certain security features (NoScript is a suspect). If it fails to upload the files try a different browser.
Update Release Version
Since 2018-04 we use Templates to maintain the versions. The previous manually updated pages are only mentioned for cross checking:
|Template:MacosPackage||4.1-2||based on Template:Version|
New Minor Stable Release
|Template:Version||4.1||based on Template:MainVersion|
New Beta Release
|Template:BetaVersion||4.900||based on Template:MainVersion|
- Currently it is unused.
- Will it be sufficient or should we have current and next?
New Major Release
|Template:FallbackMainVersion||3||The prvious MainVersion|
|Template:FallbackVersion||3.11||The last version of FallbackMainVersion|
|Minimal required OS versions:||Maintain older versions in htdocs|
|Template:Macos_Version_Supported||10.13 "High Sierra"|
- Table of Documentation at the beginning of
- De/Referenz#Liste_der_Kursquellen letzte veröffentlichte Version,
- Pt/GnuCash#Documentação tutorial e guia de conceitos do GnuCash,
- documentação de ajuda do GnuCash,
- GnuCash#The Glossary Released,
- Installation#Linux distrowatch.com,
- Using_GnuCash#Introduction links Concepts Guide and GnuCash Manual.
This are constants until we change the policy of versioning.
|Template:BetaSeries||4.9xx||based on Template:MainVersion|
Add the actual release date to Release Schedule.
If the branch for translations switches, adjust Translation Status.
Mailing list announcement
Send the same announcement to the following lists:
- Should we BCC also the user lists in other languages?
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. This works in Apple Mail as well.
The bit at the bottom about downloading from Sourceforge loses the links, so replace it with: "The latest binaries and tarballs can always be downloaded from the upper right corner of http://www.gnucash.org."
The BCCs are to prevent reply-alls from being copied to those lists, though they cause the email to get held for moderation.
Email a link of the release tarball to email@example.com.
Update the topic of irc://irc.gnome.org/gnucash: /TOPIC #gnucash Free GPL Personal and Small Business Accounting || Please don't ask to ask, just ask and wait! (Possibly a few hours!!) || publicly-logged channel || latest stable: <version> || www.gnucash.org
After logging in
- for at least Gnucash and Documentation.
Verify http://freshcode.club/projects/gnucash gets updated or adjust it. The autoupdate section is in the lower part of http://freshcode.club/submit/gnucash. It is also mirrored as https://freshfoss.com/projects/gnucash.
New Major/Minor Version
The culmination of each development cycle is the release of a new series with a new minor, and perhaps a new major, version number. Preparation for this release is typically a six-month alpha/beta release project with some special milestones.
GnuCash uses a two-part version numbering system because the Major numbers in the three part system changed so rarely as to be useless. The major number will increment with "major" releases, those which include significant new features or incompatible changes. We expect to do major releases every 2-3 years. In between, minor releases will contain bug fixes and minor new features; database schema and exposed API will not change. Unstable releases will use minor numbers beginning with 900.
Before the release of GnuCash 3.0, we used a three-part version number: Major, Minor, and Micro. Major version numbers were changed rarely and only after major architectural changes to GnuCash. Minor versions were changed when preparing a new stable series from the development, or master, branch. Unstable releases were given an odd minor version, stable releases an even minor version number. Micro version numbers were assigned sequentially to each release in a series.
In order to allow time for thorough testing and localization, it's important to set aside some development activities during the run up to a stable release. The dates that those activities stop are traditionally called freezes.
- Feature Freeze: No new features or significant architectural changes should be committed after this date to ensure that there's adequate time for the more adventurous users who act as our testers to try everything out and provide feedback.
- String Freeze: No new user-visible strings should be added after this date in order to allow translators time to finish their work by the final release date. The Translation Project requests at least two weeks, but practice suggests that a month or more is better.
- Announce the string freeze one release in advance. This would allow some GUI cleanup, check for I18n issues, join similar strings ...
- Code Freeze: Slightly misnamed, this means that only code fixing critical bugs and of limited scope, so that it's unlikely to cause regressions in other parts of the program, should be committed.
Release Schedule and Milestones
- Monthly test releases should begin 6 months before the target release date.
- The team should determine dates for feature and string freeze, and publish them on the Release Schedule.
- the Translation Project Coordinators should be notified of the first release after string freeze by emailing a link to the tarball to firstname.lastname@example.org.
- After Code Freeze test release frequency should increase to weekly. The announcements for these releases should inform testers that they are release candidates.