Difference between revisions of "Release Process"
(→Source tarballs: More detail on tarball creation) |
(→New Major Release: Add Template:CMake_Version_Docs — in case it differs from CMake_Version) |
||
(203 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | Each GnuCash release involves a number of steps for the release manager. This page is intended to gather these steps. | + | Each [[Release Schedule|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. |
− | == | + | == Commit Policy == |
− | + | Check [[Git#Branching and Merging]]. | |
− | + | You'll need write access to {{URL:GH}}flathub/org.gnucash.GnuCash/. Ask {{URL:GH}}orgs/flathub/people. | |
− | |||
− | |||
− | |||
− | == | + | == Release Process == |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | This should generate two tarballs, one bzip2 compressed and one gzip compressed. | + | |
+ | '''Notes''' | ||
+ | * 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. | ||
+ | |||
+ | === GnuCash Bundle Dependencies === | ||
+ | The Flatpak, macOS, and Windows "all-in-one" packages include all of the libraries and auxiliary programs GnuCash needs. Most of these are handled by package managers, see the respective repositories, but there are a few packages that are sufficiently unique to GnuCash that we need to manage them as part of the release process. | ||
+ | |||
+ | Check [[Dependency Sources]]. Detailed instructions are in [[Dependency Updates]]. | ||
+ | |||
+ | === Source preparation === | ||
+ | * Check out [[Git]] branch you wish to release, '''future''' or '''stable''' For example <Syntaxhighlight lang="sh"> | ||
+ | git checkout stable | ||
+ | git pull --rebase</Syntaxhighlight> | ||
+ | * 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 after making sure that both your local branches are up to date. | ||
+ | <Syntaxhighlight lang="sh"> | ||
+ | git log future..stable | ||
+ | </Syntaxhighlight> This command should not list any commits. If it does, checkout '''future''' and merge '''stable''' into it <Syntaxhighlight lang="sh"> | ||
+ | git checkout future | ||
+ | git merge stable</Syntaxhighlight> | ||
+ | * Check the pull requests on Github for any open translation pull requests from Weblate. Merge any that you find. | ||
+ | * Verify that current branch can build a distribution tarball, compile, and test it fine: <Syntaxhighlight lang="sh"> | ||
+ | cd .build | ||
+ | cmake .. | ||
+ | make | ||
+ | make distcheck</Syntaxhighlight> | ||
+ | :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 <tt>project(gnucash VERSION)</tt> | ||
+ | ** in the root <tt>CMakeLists.txt</tt> | ||
+ | ** and on major releases in <tt>README</tt> Line 4. | ||
+ | * Run <Syntaxhighlight lang="sh"> | ||
+ | util/git-release-notes.pl > release.News | ||
+ | </Syntaxhighlight> 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. | ||
+ | * If this is the first release of a '''calendar 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. | ||
+ | ** Rename ChangeLog to ChangeLog.YYYY with YYYY being the previous year. | ||
+ | ** In the root <tt>CMakeLists.txt</tt>: | ||
+ | *** Add <tt>ChangeLog.YYYY</tt> to the <tt>gnucash_DOCS</tt> variable, | ||
+ | *** Find the rule to generate the ChangeLog, update the "--since" parameter to the start of the current year. | ||
+ | ** Add the new <tt>ChangeLog.YYYY</tt> to git. | ||
+ | * Commit changes to NEWS to the git repository. | ||
+ | * Push all your changes to upstream: <Syntaxhighlight lang="sh"> | ||
+ | git push upstream maint:maint</Syntaxhighlight> | ||
+ | * Tag the new release. | ||
+ | :For example: <Syntaxhighlight lang="sh"> | ||
+ | git tag -am "Tag 3.4" 3.4 | ||
+ | </Syntaxhighlight> | ||
+ | ''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 (<Syntaxhighlight lang="sh" inline>git tag -afm "Tag 3.4" 3.4</Syntaxhighlight>) to the latest commit and make new tarballs and bundles, but you can do that only if you haven't pushed the tag. | ||
+ | '''If for some reason you must re-tag the release''' after pushing the tag to the public repo, you must use a new tag so as to not create ambiguity; we have in the past affixed a letter suffix, e.g. <code>4.8a</code>. Also delete the old tag and re-tag that release with a new one qualified with 'superseded', e.g. <code>4.8-superseded-by-4.8a</code> to make it clear later on which tag was used for the release. | ||
+ | |||
+ | === Source tarballs === | ||
+ | * 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 <tt>-e /.project -e /.cproject -e /.autotools -e /.settings/</tt> | ||
+ | * Now run | ||
+ | mkdir .build && cd .build | ||
+ | cmake .. | ||
+ | ninja && ninja distcheck | ||
+ | |||
+ | This should generate two tarballs, one bzip2 compressed and one gzip compressed. Using <tt>ninja distcheck</tt> performs several checks on the distribution before making the tarballs, then decompresses one of them, builds it, and runs <tt>ninja check</tt> 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. | ||
+ | |||
+ | === Documentation === | ||
+ | |||
+ | Now make a documentation release using the same version number as you set above for GnuCash. See [[Documentation Release Process]] for the procedure. | ||
== Windows Executable == | == Windows Executable == | ||
− | The creation of the | + | 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 {{URL:Build:Win}}. |
− | |||
− | == | + | '''''Don't do either of these steps:''''' |
− | This | + | Strawberry Perl have moved their downloads to github.com for versions after 5.32.1.1 and appears to be providing only 64-bit versions after 5.38.1.1. MSXML2, used to download the Perl installer, reports access denied when pointed at the github.com URI and Microsoft has killed off VBS for future development and will be removing it [https://techcommunity.microsoft.com/t5/windows-it-pro-blog/vbscript-deprecation-timelines-and-next-steps/ba-p/4148301 in 2027]. |
+ | |||
+ | We have custom translations in Innosetup that are not compatible with later versions. | ||
+ | |||
+ | ;Perl version: Check {{URL:SBP}} for the recommended version and update <tt>strVersion</tt> in [{{URL:git}}gnucash-on-windows/blob/master/extra_dist/getperl.vbs extra_dist/getperl.vbs]. | ||
+ | :From [{{URL:git}}gnucash-on-windows/pull/15/commits/12152926645f7b0bd0223aa0f7584a3f23a884fb PR#15] | ||
+ | |||
+ | ;Innosetup version: Check {{URL:JRSW}}isdl.php for updates. | ||
+ | :* Can we drop custom language files, because they have become [{{URL:JRSW}}files/istrans/ official]? | ||
+ | :* Are there updates for unofficial translations? | ||
+ | |||
+ | == MacOS Executable == | ||
+ | This package is usually created by [[User:Jralls | John Ralls]] using this [[MacOS/Quartz#Making_a_distribution | procedure]] . | ||
== Sourceforge file uploads == | == Sourceforge file uploads == | ||
All the above build targets should be uploaded to Source Forge. | All the above build targets should be uploaded to Source Forge. | ||
− | * Log in on the [[ | + | # Make SHA256 digests of the two tarballs and the three installer packages, e.g.<syntaxhighlight lang="sh"> |
− | + | sha256sum gnucash-*.tar.* > README.sha | |
− | + | sha256sum Gnucash*.dmg >> README.sha | |
− | * Upload the files created above to this directory. | + | sha256sum gnucash*.setup.exe >> README.sha |
− | + | </syntaxhighlight> | |
+ | # Log in on the [[{{URL:SF}}projects/gnucash/ Source Forge GnuCash website]] | ||
+ | ## Go to the Project Admin -> File Manager section | ||
+ | ## Create a new directory for the release, either under | ||
+ | ##* <tt>gnucash (stable)</tt> or | ||
+ | ##* <tt>gnucash (unstable)</tt>. | ||
+ | ##: Mark it <q>staged</q> 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. | ||
+ | |||
+ | == Flathub package == | ||
+ | |||
+ | === Preparation === | ||
+ | You will need push privileges on {{BuildServer}} and {{URL:GH}}flathub/org.gnucash.Gnucash. The latter must be requested from the flathub admins and requires that you have a Github userid with a public key installed. | ||
+ | |||
+ | # Log in to github in your browser and fork {{URL:GH}}flathub/org.gnucash.Gnucash. | ||
+ | # Create a container directory, e.g. <tt>gnucash-flatpak</tt> with two subdirectories, <tt>build</tt> and <tt>source</tt>. | ||
+ | # Change to the src directory and clone four repositories: | ||
+ | #* <tt>ssh:{{BuildServer}}/gnucash-on-flatpak</tt> If you prefer you can clone <tt>{{URL:git}}gnucash-on-flatpak</tt> and set up the ssh URL as a second remote in that repository. | ||
+ | #* <tt>{{URL:git}}gnucash</tt> | ||
+ | #* <tt>{{URL:git}}gnucash-docs</tt> | ||
+ | #* <tt>git@github.com:your-github-userid/org.gnucash.Gnucash</tt>. | ||
+ | # In the <tt>org.gnucash.GnuCash</tt> repository create a <tt>flathub</tt> remote pointing to <tt>{{URL:GH}}flathub/org.gnucash.Gnucash</tt>. | ||
+ | # Follow {{URL:git}}gnucash-on-flatpak/blob/master/README.md to set up a gnucash-on-flatpak build environment. | ||
+ | |||
+ | Once this is setup it does not need to be repeated. | ||
+ | |||
+ | === Build a test release from gnucash-on-flatpak === | ||
+ | <ol> | ||
+ | <li>Checkout the branch for the release type: For ''stable'' releases use the <tt>master</tt> branch; for ''unstable'' releases use the <tt>unstable</tt> branch.</li> | ||
+ | <li>Update the repo to the latest commit: | ||
+ | git pull --rebase | ||
+ | </li> | ||
+ | <li>'''June and December''': Update <tt>org.gnucash.GnuCash.json</tt> <code>runtime-version</code> to the latest Gnome release.</li> | ||
+ | <li>Change directories to the <tt>../../build</tt>.</li> | ||
+ | <li>Run<pre> | ||
+ | build_package.sh -r{{Version}} -c{{Version}} -d{{Version}} | ||
+ | </pre> | ||
+ | changing the version number to the one you want to release. | ||
+ | * 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). | ||
+ | </li> | ||
+ | <li>Make sure that the build completes satisfactorily. If it doesn't you'll have to troubleshoot the problem and fix it before continuing. Don't forget to commit and push any changes and to retag if necessary.</li> | ||
+ | <li><tt>build_package.sh</tt> will generate/update 3 files in the base directory of the gnucash-on-flatpak repository:<pre> | ||
+ | gnucash-source.json | ||
+ | gnucash-docs-source.json | ||
+ | gnucash-extra-modules.json | ||
+ | </pre> | ||
+ | </li></ol> | ||
+ | |||
+ | === Package the Release on Flathub === | ||
+ | <ol> | ||
+ | <li>Change directory to <tt>../src/org.gnucash.Gnucash</tt> and pull to ensure your repo is up to date with the <tt>flathub</tt> remote.</li> | ||
+ | <li>Checkout the branch corresponding to the release type. As in <tt>gnucash-on-flatpak</tt> for ''stable'' releases use the <tt>master</tt> branch. For ''unstable'' releases use the <tt>beta</tt> branch.</li> | ||
+ | <li>Copy all modules, patches, and <tt>org.gnucash.Gnucash.json</tt> from <tt>gnucash-on-flatpak</tt>:<br/> | ||
+ | <pre> | ||
+ | cp ../gnucash-on-flatpak/modules/*.json modules/ | ||
+ | cp ../gnucash-on-flatpak/patches/*.patch patches/ | ||
+ | cp ../gnucash-on-flatpak/org.gnucash.GnuCash . | ||
+ | </pre></li> | ||
+ | <li>Copy the files created by <tt>build_package.sh</tt> and commit:<pre> | ||
+ | cp ../gnucash-on-flatpak/gnucash-source.json . | ||
+ | cp ../gnucash-on-flatpak/gnucash-docs-source.json | ||
+ | cp ../gnucash-on-flatpak/gnucash-extra-modules.json | ||
+ | git commit -am "Update to upstream X.Y" | ||
+ | </pre></li> | ||
+ | <li>Find the most recent tag:<pre> | ||
+ | git tag | tail -n 1 | ||
+ | </pre></li> | ||
+ | <li>Run command<pre> | ||
+ | git log --date=short --format="<li>%ad - %s (%an)</li>" <tag>..HEAD | ||
+ | </pre> | ||
+ | where <tag> is the tag from the previous step.</li> | ||
+ | <li>Use the result of this command to update <tt>gnucash.releases.xml</tt>. Add lines for new builds, start over at each new release. It tracks changes made to the flatpak that are outside of the gnucash release cadence (like rebuilding with a newer aqbanking version). </li> | ||
+ | <li>Open <tt>org.gnucash.Gnucash</tt> in your favorite editor, find the <tt>modules</tt> section, and under <tt>config.opts</tt> add<pre> | ||
+ | "-DGNUCASH_BUILD_ID='Flathub X.Y-Z'" | ||
+ | </pre></li> | ||
+ | <li>Commit these changes, tag them, and push:<pre> | ||
+ | git commit -am "Package gnucash X.Y-Z" | ||
+ | git tag -am "Package gnucash X.Y-Z" X.Y-Z | ||
+ | git push origin <branch> | ||
+ | </pre> | ||
+ | where <branch> is the one checked out in the first step.</li> | ||
+ | <li>Open your <tt>org.gnucash.GnuCash</tt> fork in a web browser. You'll see your latest commit in the top banner. At the right side of the banner is a '''Contribute''' button. Click it and then click the '''Open Pull Request''' button. | ||
+ | |||
+ | In the pull request page add a title such as "Release GnuCash X.Y-Z" and click the create button. After a few seconds it will notify you that the CI checks have begun.</li> | ||
+ | <li>Check the flathub build process at | ||
+ | *Stable releases: {{URL:FH}}builds/#/apps/org.gnucash.GnuCash | ||
+ | *Unstable releases: {{URL:FH}}builds/#/apps/org.gnucash.GnuCash~2Fbeta | ||
+ | |||
+ | <p>Click the flashing yellow label to see the build details. | ||
+ | If the build fails a step but proceeds to another, stop it (see below). Even if the build step is successful the product will be deleted, not installed; likewise if one architecture build fails and the other succeeds the build result will be discarded.</p> | ||
+ | |||
+ | <p>In the event of a failure determine the cause. If it's a transient failure like a failed download you can restart the build without any changes in the repository. If the build fails because of a problem in one of the module files or a compilation error you'll need to fix it and make a new tag by incrementing the Z value and pushing the fixed branch to flathub. Be sure to make any changes in <tt>gnucash-on-flatpak</tt> and copy them to <tt>org.gnucash.GnuCash</tt>; we want the descriptive commit messages in the former.</p> | ||
+ | |||
+ | <p>To stop and restart jobs you must first log in: Click the '''Anonymous''' label in the upper right corner of the flathub webpage and select '''Login with Github''' and login with your Github credentials.</p> | ||
+ | |||
+ | <p>If a build is running you'll find a button that says Stop just to the left of your name. It does just that. Once a job is stopped or has failed the button will say Restart. If the build failed for a transient reason then you can click that when the failure has been resolved. That 'queues' a new job; it may take a while for it to start. Meanwhile it will display the default parameters for the job with a Cancel button replacing the Restart button. When the job starts it will display a new build page.</p></li> | ||
+ | <li>There are normally two jobs, one for x86_64 and one for aarch-64. When the x86_64 one succeeds you can push to flathub. Don't forget to push your tag! | ||
+ | <syntaxhighlight lang="sh"> | ||
+ | git push flathub <branch> | ||
+ | git push flathub X.Y-Z | ||
+ | </syntaxhighlight></li> | ||
+ | </ol> | ||
+ | |||
+ | === Build Numbering === | ||
+ | We've used the notation '''X.Y-Z''' in several places above. '''X''' and '''Y''' are the release major and minor version, '''Z''' is the flathub build number in a release. We don't use one for the first build of a release; that will use just X.Y. Z comes from running | ||
+ | git describe --match X.Y | ||
+ | and discarding the commit hash; that means that Z may not be sequential with the previous one, as there may be more than one commit between builds. | ||
+ | |||
+ | == Git housekeeping after a release == | ||
+ | |||
+ | === All releases === | ||
+ | If any changes were committed during the release steps above, merge these upwards to the other upstream branches if any. For example if you committed something to stable, merge stable into future: | ||
+ | <syntaxhighlight lang="sh"> | ||
+ | git checkout future | ||
+ | git merge --no-ff stable | ||
+ | </syntaxhighlight> | ||
+ | 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 future. There may be other merge conflicts. Evaluate them and fix them accordingly. | ||
+ | |||
+ | === 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 4.x to 5.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 future branch. This commit should now become the HEAD commit for the stable branch because it will be used for all subsequent releases in the new series. | ||
+ | |||
+ | In git: | ||
+ | <syntaxhighlight lang="sh"> | ||
+ | git checkout stable | ||
+ | git merge --ff-only future | ||
+ | git branch -D future | ||
+ | </syntaxhighlight> | ||
+ | The merge will fail if stable has commits that aren't in future. If that happens start over at [#Source Preparation] and make sure that future is a superset of stable then rebuild the release. | ||
+ | |||
+ | The last command removes the future branch. We use that branch only when there is work that can't be released in the current stable series. | ||
+ | |||
+ | ==== Update CI files==== | ||
+ | Usually a new major release will require more recent distributions of Ubuntu …—both in program and documentation. | ||
+ | |||
+ | == GnuCash Website == | ||
+ | |||
+ | '''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|Git wiki page]] to prepare a local gnucash-htdocs repository with commit access to the primary repository on {{BuildServer}}. Be sure to follow the [[Git#Committers (for pure git repositories)|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 <Syntaxhighlight lang="sh> | ||
+ | cd gnucash-htdocs.git | ||
+ | git checkout master | ||
+ | git pull upstream | ||
+ | </Syntaxhighlight> | ||
+ | # Go to the news files <Syntaxhighlight lang="sh> | ||
+ | cd news | ||
+ | </Syntaxhighlight> | ||
+ | # Copy the last release newsfile. The filename format is usually <tt>YYMMDD-<releasenumber>.news</tt>. For example:<Syntaxhighlight lang="sh> | ||
+ | cd gnucash-htdocs.git | ||
+ | cp 130430-2.5.1.news 130527-2.5.2.news | ||
+ | </Syntaxhighlight> | ||
+ | # 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: <Syntaxhighlight lang="sh> | ||
+ | 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 | ||
+ | </Syntaxhighlight> | ||
+ | # 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 | ||
+ | # [[Website Maintenance#W3C Validation|Tidy]] the file. | ||
+ | # Add the new file to revision control <Syntaxhighlight lang="sh> | ||
+ | git add 130527-2.5.2.news | ||
+ | </Syntaxhighlight> | ||
+ | |||
+ | === 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. | ||
+ | |||
+ | === New Major Release === | ||
+ | ;download.phtml: Copy "Last version for <OS><Version>" elements from <syntaxhighlight lang="html" inline><div id="previous" …></syntaxhighlight> to <syntaxhighlight lang="html" inline><div id="historical" …></syntaxhighlight> and replace there then "$old_stable*" by "$last_*" variables. On demand create them in <tt>externals/global_params.php</tt>. | ||
+ | |||
+ | ;docs.phtml: needs a new section in $older<n> as long as we do not convert it in a loop with version dependend LANGs. | ||
+ | ;viewdoc.phtml: Add previous version to | ||
+ | # Parse requested version | ||
+ | ;robots.txt: | ||
+ | Disallow: /docs/v<ancestor({{MainVersion}})> / | ||
+ | |||
+ | === Commit the changes. === | ||
+ | |||
+ | Finally, all these changes to the website should be committed. From the base directory: | ||
+ | git checkout beta | ||
+ | git merge master | ||
+ | git add <changed-files> | ||
+ | git commit -m "Announce Release of GnuCash x.y" | ||
+ | git push upstream beta | ||
+ | git checkout master | ||
+ | git merge beta | ||
+ | git push upstream master | ||
+ | |||
+ | The last command will take care of updating the live website. | ||
+ | |||
+ | == GitHub == | ||
+ | Set up a new release on GitHub: | ||
+ | # Go to [{{URL:git}}gnucash/releases 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. | ||
+ | |||
+ | == GnuCash Wiki == | ||
+ | === Update Release Version === | ||
+ | Since 2018-04 we use [{{URL:MW}}Help:Templates Templates] to maintain the versions. The previous manually updated pages are only mentioned for cross checking: | ||
+ | ==== New Packages ==== | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! scope="col"| Address | ||
+ | ! scope="col"| Content | ||
+ | ! scope="col"| Note | ||
+ | ! scope="col"| Nightly ( >= ? ) | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:MacosArmPackage]] | ||
+ | |{{Template:MacosArmPackage}} | ||
+ | |based on [[Template:Version]] | ||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Macosx86Package]] | ||
+ | |{{Template:Macosx86Package}} | ||
+ | |based on [[Template:Version]] | ||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:WindowsPackage]] | ||
+ | |{{Template:WindowsPackage}} | ||
+ | |based on [[Template:Version]] | ||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:DocPackage]] | ||
+ | |{{Template:DocPackage}} | ||
+ | |based on [[Template:Version]] | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |colspan="4"| '''Bundled Packages''' | ||
+ | |||
+ | |- style="vertical-align:center;" | ||
+ | |rowspan="2"|[[Template:AqB_Version]] | ||
+ | |rowspan="2"|{{AqB Version}} | ||
+ | |current Win nightly: {{AqB Version nightly}} | ||
+ | |[[Template:AqB Version nightly]] | ||
+ | |- style="vertical-align:top;" | ||
+ | |current FP nightly: {{AqB Version nightly FP}} | ||
+ | |[[Template:AqB Version nightly FP]] | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:FQ_Version]] | ||
+ | |{{FQ Version}} | ||
+ | |current nightly: {{FQ Version nightly}} | ||
+ | |[[Template:FQ Version nightly]] | ||
+ | |} | ||
+ | * [[MacOS/Quartz#Downloads]] | ||
+ | |||
+ | ==== New Minor Stable Release ==== | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! scope="col"| Address | ||
+ | ! scope="col"| Content | ||
+ | ! scope="col"| Note | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Version]] | ||
+ | |{{Template:Version}} | ||
+ | |based on [[Template:MainVersion]] | ||
+ | |} | ||
+ | * [[QA/BugzillaAdministration#When_closing_an_old_bug_as_OBSOLETE]] | ||
+ | |||
+ | ==== New Beta Release ==== | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! scope="col"| Address | ||
+ | ! scope="col"| Content | ||
+ | ! scope="col"| Note | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:BetaVersion]] | ||
+ | |{{Template:BetaVersion}} | ||
+ | |based on [[Template:MainVersion]] | ||
+ | |} | ||
+ | ;Note: Currently it is unused. | ||
+ | ;Fixme: Will it be sufficient or should we have ''current'' and ''next''? | ||
+ | |||
+ | ==== New Major Release ==== | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! scope="col"| Address | ||
+ | ! scope="col"| Content | ||
+ | ! scope="col"| Notes | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:MainVersion]] | ||
+ | |{{Template:MainVersion}} | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:FallbackMainVersion]] | ||
+ | |{{Template:FallbackMainVersion}} | ||
+ | |The previous MainVersion | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:FallbackVersion]] | ||
+ | |{{Template:FallbackVersion}} | ||
+ | |The last version of FallbackMainVersion | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |colspan="2"| '''Minimal required OS versions''' | ||
+ | |We maintain older versions in htdocs only | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Macos_Arm_Version_Supported]] | ||
+ | |{{Template:Macos_Arm_Version_Supported}} | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Macos_x86_Version_Supported]] | ||
+ | |{{Template:Macos_x86_Version_Supported}} | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Windows_Version_Supported]] | ||
+ | |{{Template:Windows_Version_Supported}} | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |colspan="3"| '''Build Dependencies''' | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:CMake_Version]] | ||
+ | |{{CMake_Version}} | ||
+ | |The oldest supported Version | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:CMake_Version_Docs]] | ||
+ | |{{CMake_Version_Docs}} | ||
+ | |The documented Version, if different | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Boost_Version]] | ||
+ | |{{Boost_Version}} | ||
+ | |[[I18N#Strings in C++ files]], [[I18N#Formatted strings]] | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |colspan="3"| '''Build Dependencies Optional''' | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Python Major]] | ||
+ | |{{Python Major}} | ||
+ | | | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Python Minor]] | ||
+ | |{{Python Minor}} | ||
+ | | | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:Python Version]] | ||
+ | |{{Python Version}} | ||
+ | |based on Python Major & Python Minor | ||
+ | |} | ||
+ | :;Tip: To find all appearances, in a template see <tt>What links here</tt>(?). | ||
+ | |||
+ | ==== Policy Change ==== | ||
+ | This are constants until we change the policy of versioning. | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! scope="col"| Address | ||
+ | ! scope="col"| Content | ||
+ | ! scope="col"| Note | ||
+ | |||
+ | |- style="vertical-align:top;" | ||
+ | |[[Template:BetaSeries]] | ||
+ | |{{Template:BetaSeries}} | ||
+ | |based on [[Template:MainVersion]] | ||
+ | |} | ||
+ | |||
+ | === Release Schedule === | ||
+ | Add the actual release date to [[Release Schedule]]. | ||
+ | |||
+ | == Mailing list announcement == | ||
+ | |||
+ | Send the same announcement to the following lists: | ||
+ | * [mailto:gnucash-user@gnucash.org gnucash-user@gnucash.org] | ||
+ | * CC [mailto:gnucash-devel@gnucash.org gnucash-devel@gnucash.org] | ||
+ | * CC [mailto:gnucash-announce@gnucash.org gnucash-announce@gnucash.org] | ||
+ | * Reply-to: gnucash-user@gnucash.org | ||
+ | ;Question: 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 {{URL:www}}." | ||
+ | |||
+ | The BCCs are to prevent reply-alls from being copied to those lists, though they cause the email to get held for moderation. | ||
+ | |||
+ | == IRC == | ||
+ | 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> || {{URL:www}} | ||
+ | |||
+ | == Bugzilla == | ||
+ | After logging in | ||
+ | * [{{URL:Bugs}}editversions.cgi?action=add&product=GnuCash Add the new version number] and eventually | ||
+ | * [{{URL:Bugs}}editmilestones.cgi?action=add&product=GnuCash add the next milestone] | ||
+ | : for at least Gnucash and Documentation. | ||
+ | |||
+ | == Promotion == | ||
+ | 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. | ||
+ | |||
+ | * {{URL:FB}}: [[User:CMarchi]] once had set it up. | ||
+ | |||
+ | = 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. | ||
− | == | + | === Version Numbers === |
− | + | 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | === Freezes === | |
− | + | 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 [{{URL:wp}}Freeze_(software_engineering)''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. We will typically freeze 2 weeks in advance of a minor release and 4 weeks in advance of a major release. | ||
+ | :;Suggestion: For major releases 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 3 months before the target release date. | |
+ | * The team should determine dates for feature and string freeze, and publish them on the [[Release Schedule]]. | ||
+ | * After Code Freeze test release frequency should increase to weekly. The announcements for these releases should inform testers that they are ''release candidates''. | ||
− | + | [[Category:Releases]] |
Latest revision as of 16:09, 3 October 2024
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.
Contents
Commit Policy
Check Git#Branching and Merging. You'll need write access to https://github.com/flathub/org.gnucash.GnuCash/. Ask https://github.com/orgs/flathub/people.
Release Process
Notes
- 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.
GnuCash Bundle Dependencies
The Flatpak, macOS, and Windows "all-in-one" packages include all of the libraries and auxiliary programs GnuCash needs. Most of these are handled by package managers, see the respective repositories, but there are a few packages that are sufficiently unique to GnuCash that we need to manage them as part of the release process.
Check Dependency Sources. Detailed instructions are in Dependency Updates.
Source preparation
- Check out Git branch you wish to release, future or stable For example
git checkout stable git pull --rebase
- 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 after making sure that both your local branches are up to date.
git log future..stable
git checkout future
git merge stable
- Check the pull requests on Github for any open translation pull requests from Weblate. Merge any that you find.
- 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
- and on major releases in README Line 4.
- 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:
- 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.
- Rename 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.
- Add the new ChangeLog.YYYY to git.
- Commit changes to NEWS to the git repository.
- Push all your changes to upstream:
git push upstream maint:maint
- 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.
If for some reason you must re-tag the release after pushing the tag to the public repo, you must use a new tag so as to not create ambiguity; we have in the past affixed a letter suffix, e.g. 4.8a
. Also delete the old tag and re-tag that release with a new one qualified with 'superseded', e.g. 4.8-superseded-by-4.8a
to make it clear later on which tag was used for the release.
Source tarballs
- 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.
Documentation
Now make a documentation release using the same version number as you set above for GnuCash. See Documentation Release Process for the procedure.
Windows Executable
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 https://code.gnucash.org/builds/win32/stable/?C=M;O=D.
Don't do either of these steps: Strawberry Perl have moved their downloads to github.com for versions after 5.32.1.1 and appears to be providing only 64-bit versions after 5.38.1.1. MSXML2, used to download the Perl installer, reports access denied when pointed at the github.com URI and Microsoft has killed off VBS for future development and will be removing it in 2027.
We have custom translations in Innosetup that are not compatible with later versions.
- Perl version
- Check https://strawberryperl.com/ for the recommended version and update strVersion in extra_dist/getperl.vbs.
- From PR#15
- Innosetup version
- Check https://jrsoftware.org/isdl.php for updates.
- Can we drop custom language files, because they have become official?
- Are there updates for unofficial translations?
MacOS Executable
This package is usually created by John Ralls using this procedure .
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.
Flathub package
Preparation
You will need push privileges on code.gnucash.org and https://github.com/flathub/org.gnucash.Gnucash. The latter must be requested from the flathub admins and requires that you have a Github userid with a public key installed.
- Log in to github in your browser and fork https://github.com/flathub/org.gnucash.Gnucash.
- Create a container directory, e.g. gnucash-flatpak with two subdirectories, build and source.
- Change to the src directory and clone four repositories:
- ssh:code.gnucash.org/gnucash-on-flatpak If you prefer you can clone https://github.com/Gnucash/gnucash-on-flatpak and set up the ssh URL as a second remote in that repository.
- https://github.com/Gnucash/gnucash
- https://github.com/Gnucash/gnucash-docs
- git@github.com:your-github-userid/org.gnucash.Gnucash.
- In the org.gnucash.GnuCash repository create a flathub remote pointing to https://github.com/flathub/org.gnucash.Gnucash.
- Follow https://github.com/Gnucash/gnucash-on-flatpak/blob/master/README.md to set up a gnucash-on-flatpak build environment.
Once this is setup it does not need to be repeated.
Build a test release from gnucash-on-flatpak
- Checkout the branch for the release type: For stable releases use the master branch; for unstable releases use the unstable branch.
- Update the repo to the latest commit: git pull --rebase
- June and December: Update org.gnucash.GnuCash.json
runtime-version
to the latest Gnome release. - Change directories to the ../../build.
- Run
build_package.sh -r{{Version}} -c{{Version}} -d{{Version}}
changing the version number to the one you want to release.
- 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).
- Make sure that the build completes satisfactorily. If it doesn't you'll have to troubleshoot the problem and fix it before continuing. Don't forget to commit and push any changes and to retag if necessary.
- build_package.sh will generate/update 3 files in the base directory of the gnucash-on-flatpak repository:
gnucash-source.json gnucash-docs-source.json gnucash-extra-modules.json
Package the Release on Flathub
- Change directory to ../src/org.gnucash.Gnucash and pull to ensure your repo is up to date with the flathub remote.
- Checkout the branch corresponding to the release type. As in gnucash-on-flatpak for stable releases use the master branch. For unstable releases use the beta branch.
- Copy all modules, patches, and org.gnucash.Gnucash.json from gnucash-on-flatpak:
cp ../gnucash-on-flatpak/modules/*.json modules/ cp ../gnucash-on-flatpak/patches/*.patch patches/ cp ../gnucash-on-flatpak/org.gnucash.GnuCash .
- Copy the files created by build_package.sh and commit:
cp ../gnucash-on-flatpak/gnucash-source.json . cp ../gnucash-on-flatpak/gnucash-docs-source.json cp ../gnucash-on-flatpak/gnucash-extra-modules.json git commit -am "Update to upstream X.Y"
- Find the most recent tag:
git tag | tail -n 1
- Run command
git log --date=short --format="<li>%ad - %s (%an)</li>" <tag>..HEAD
where <tag> is the tag from the previous step. - Use the result of this command to update gnucash.releases.xml. Add lines for new builds, start over at each new release. It tracks changes made to the flatpak that are outside of the gnucash release cadence (like rebuilding with a newer aqbanking version).
- Open org.gnucash.Gnucash in your favorite editor, find the modules section, and under config.opts add
"-DGNUCASH_BUILD_ID='Flathub X.Y-Z'"
- Commit these changes, tag them, and push:
git commit -am "Package gnucash X.Y-Z" git tag -am "Package gnucash X.Y-Z" X.Y-Z git push origin <branch>
where <branch> is the one checked out in the first step. - Open your org.gnucash.GnuCash fork in a web browser. You'll see your latest commit in the top banner. At the right side of the banner is a Contribute button. Click it and then click the Open Pull Request button. In the pull request page add a title such as "Release GnuCash X.Y-Z" and click the create button. After a few seconds it will notify you that the CI checks have begun.
- Check the flathub build process at
- Stable releases: https://flathub.org/builds/#/apps/org.gnucash.GnuCash
- Unstable releases: https://flathub.org/builds/#/apps/org.gnucash.GnuCash~2Fbeta
Click the flashing yellow label to see the build details. If the build fails a step but proceeds to another, stop it (see below). Even if the build step is successful the product will be deleted, not installed; likewise if one architecture build fails and the other succeeds the build result will be discarded.
In the event of a failure determine the cause. If it's a transient failure like a failed download you can restart the build without any changes in the repository. If the build fails because of a problem in one of the module files or a compilation error you'll need to fix it and make a new tag by incrementing the Z value and pushing the fixed branch to flathub. Be sure to make any changes in gnucash-on-flatpak and copy them to org.gnucash.GnuCash; we want the descriptive commit messages in the former.
To stop and restart jobs you must first log in: Click the Anonymous label in the upper right corner of the flathub webpage and select Login with Github and login with your Github credentials.
If a build is running you'll find a button that says Stop just to the left of your name. It does just that. Once a job is stopped or has failed the button will say Restart. If the build failed for a transient reason then you can click that when the failure has been resolved. That 'queues' a new job; it may take a while for it to start. Meanwhile it will display the default parameters for the job with a Cancel button replacing the Restart button. When the job starts it will display a new build page.
- There are normally two jobs, one for x86_64 and one for aarch-64. When the x86_64 one succeeds you can push to flathub. Don't forget to push your tag!
git push flathub <branch> git push flathub X.Y-Z
Build Numbering
We've used the notation X.Y-Z in several places above. X and Y are the release major and minor version, Z is the flathub build number in a release. We don't use one for the first build of a release; that will use just X.Y. Z comes from running
git describe --match X.Y
and discarding the commit hash; that means that Z may not be sequential with the previous one, as there may be more than one commit between builds.
Git housekeeping after a release
All releases
If any changes were committed during the release steps above, merge these upwards to the other upstream branches if any. For example if you committed something to stable, merge stable into future:
git checkout future
git merge --no-ff stable
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 future. There may be other merge conflicts. Evaluate them and fix them accordingly.
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 4.x to 5.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 future branch. This commit should now become the HEAD commit for the stable branch because it will be used for all subsequent releases in the new series.
In git:
git checkout stable
git merge --ff-only future
git branch -D future
The merge will fail if stable has commits that aren't in future. If that happens start over at [#Source Preparation] and make sure that future is a superset of stable then rebuild the release.
The last command removes the future branch. We use that branch only when there is work that can't be released in the current stable series.
Update CI files
Usually a new major release will require more recent distributions of Ubuntu …—both in program and documentation.
GnuCash Website
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
cd news
- Copy the last release newsfile. The filename format is usually YYMMDD-<releasenumber>.news. For example:
cd gnucash-htdocs.git 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
- Tidy the file.
- 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.
New Major Release
- download.phtml
- 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.
- docs.phtml
- needs a new section in $older<n> as long as we do not convert it in a loop with version dependend LANGs.
- viewdoc.phtml
- Add previous version to
# Parse requested version
- robots.txt
Disallow: /docs/v<ancestor(5)> /
Commit the changes.
Finally, all these changes to the website should be committed. From the base directory:
git checkout beta git merge master git add <changed-files> git commit -m "Announce Release of GnuCash x.y" git push upstream beta git checkout master git merge beta git push upstream master
The last command will take care of updating the live website.
GitHub
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.
GnuCash Wiki
Update Release Version
Since 2018-04 we use Templates to maintain the versions. The previous manually updated pages are only mentioned for cross checking:
New Packages
Address | Content | Note | Nightly ( >= ? ) |
---|---|---|---|
Template:MacosArmPackage | 5.10-1 | based on Template:Version | |
Template:Macosx86Package | 5.10-1 | based on Template:Version | |
Template:WindowsPackage | 5.10 | based on Template:Version | |
Template:DocPackage | 5.10 | based on Template:Version | |
Bundled Packages | |||
Template:AqB_Version | 6.5.4 | current Win nightly: 6.5.12beta | Template:AqB Version nightly |
current FP nightly: 6.5.12beta | Template:AqB Version nightly FP | ||
Template:FQ_Version | 1.64 | current nightly: 1.64 | Template:FQ Version nightly |
New Minor Stable Release
Address | Content | Note |
---|---|---|
Template:Version | 5.10 | based on Template:MainVersion |
New Beta Release
Address | Content | Note |
---|---|---|
Template:BetaVersion | 5.900 | based on Template:MainVersion |
- Note
- Currently it is unused.
- Fixme
- Will it be sufficient or should we have current and next?
New Major Release
Address | Content | Notes |
---|---|---|
Template:MainVersion | 5 | |
Template:FallbackMainVersion | 4 | The previous MainVersion |
Template:FallbackVersion | 4.14 | The last version of FallbackMainVersion |
Minimal required OS versions | We maintain older versions in htdocs only | |
Template:Macos_Arm_Version_Supported | 11 "Big Sur" | |
Template:Macos_x86_Version_Supported | 10.13 "High Sierra" | |
Template:Windows_Version_Supported | 10/11 | |
Build Dependencies | ||
Template:CMake_Version | 3.14.5 | The oldest supported Version |
Template:CMake_Version_Docs | 3.14 | The documented Version, if different |
Template:Boost_Version | 1_67_0 | I18N#Strings in C++ files, I18N#Formatted strings |
Build Dependencies Optional | ||
Template:Python Major | 3 | |
Template:Python Minor | 6 | |
Template:Python Version | 3.6 | based on Python Major & Python Minor |
- Tip
- To find all appearances, in a template see What links here(?).
Policy Change
This are constants until we change the policy of versioning.
Address | Content | Note |
---|---|---|
Template:BetaSeries | 5.9xx | based on Template:MainVersion |
Release Schedule
Add the actual release date to Release Schedule.
Mailing list announcement
Send the same announcement to the following lists:
- gnucash-user@gnucash.org
- CC gnucash-devel@gnucash.org
- CC gnucash-announce@gnucash.org
- Reply-to: gnucash-user@gnucash.org
- Question
- 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 https://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.
IRC
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> || https://www.gnucash.org/
Bugzilla
After logging in
- Add the new version number and eventually
- add the next milestone
- for at least Gnucash and Documentation.
Promotion
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.
- https://www.facebook.com/Gnucash/: User:CMarchi once had set it up.
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.
Version Numbers
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.
Freezes
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. We will typically freeze 2 weeks in advance of a minor release and 4 weeks in advance of a major release.
- Suggestion
- For major releases 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 3 months before the target release date.
- The team should determine dates for feature and string freeze, and publish them on the Release Schedule.
- After Code Freeze test release frequency should increase to weekly. The announcements for these releases should inform testers that they are release candidates.