Latest revision as of 22:18, 20 August 2023

'Developer notes for What to do for a release '

Note that the main use of this page will be for making a normal "minor" release. If you are making a "major" release (e.g. x.y.0) then you will need to update this page first, to change the numbers. But if you are only making an "alpha" or "beta" release, some steps may be skipped, or altered slightly.

Note also that there are additional necessary Post release tasks which are related to making a new release. For instance, the wiki will require making a new release-section and updating "General" version templates. For the making a new release-section on the bug tracker. Or when making new Debian and Mac and Windows packaging, they will need to be coordinated with the appropriate package maintainers and updating the corresponding Versions : Templates.

Pre-release

Agree a release timetable

Co-ordinate with the package maintainers to agree a release timetable. For a major release there may be a schedule on the Roadmap

Announce a feature freeze

For a major release, announce a feature freeze on the gramps-devel mailing list. This will usually be about 4 weeks before the release date.

Translation update

The translation template should be updated, if necessary, just before the string freeze is announced.

Check for new files since the last release:

 cd po
 intltool-update -m

That will create a file called missingin the po directory if there are new files that need to be scanned for translatable strings. Examine each of the files listed in missing, adding each to POTFILES.in if it contains translatable string constants and to POTFILES.skip if it does not.

Generate a new template file:

 python3 update_po.py -p # makes a new gramps.pot template file
 git diff gramps.pot

Examine the changes. If they're all just comments about where a string is found you need not commit the change (so the next line will restore the official file, instead of the one you just made):

 git restore gramps.pot

If there have been changes on msgid entries, you'll need to commit gramps.pot and ask translators to update their .po files before you can make a release:

 git add gramps.pot
 git commit -m "Update translation template for new release"

Check current translation files (there must be no 'fatal' errors):

 python3 update_po.py -k all

Also see:

Template:Gramps_translations#INCOMPLETE_TRANSLATIONS - Update if any translation needs to be added or excluded due to not meeting the minimum 70% completion requirement.

Announce a string freeze

For a major release, announce a string freeze on the gramps-devel mailing list and on Weblate. This will usually be about 2 weeks before the release date.

Prepare your repository

Check out the current stable branch:

 git checkout maintenance/gramps51

That branch name assumes that you're using the same name as the Github repository; if you're not (perhaps you don't use maintenance in the name) use your local name.

Make sure that your local copy is clean:

 git status

If you have any uncommitted changes, either commit them now or stash them until after you've completed the release.

Clean up any untracked files and make sure that the local repo is up to date:

 git clean -fdx
 git pull --rebase

If you had commits that hadn't been pushed yet they'll show up as "applying" messages in the output of this command. If that's the case re-run the tests and push as usual.

Build and test to make sure that everything works, then clean the repo of all build products.

Check the About box year

Check if the year in the About box needs to be updated

eg:

  © 2007-2021 The Gramps Developers

to

  © 2007-2022 The Gramps Developers.

Found in gramps/gen/const.py

API docs update year

If needed in the file:

docs/conf.py

Update the year for the copyright.

copyright = '2001-2022, The Gramps Project'

Update Classifier in setup.py

Change Classifier to the appropriate one in setup.py (master is always the first one)

Development Status :: 1 - Planning
Development Status :: 2 - Pre-Alpha
Development Status :: 3 - Alpha
Development Status :: 4 - Beta
Development Status :: 5 - Production/Stable

Check if any additional language classifier needs to be added also.

Update the 'behavior.betawarn' key value

If the release is Production/Stable make sure that the behavior.betawarn key value has been set to False e.g., https://github.com/gramps-project/gramps/commit/9dc976f28dc16c514e9e8e0b0fa09338bfe04f8a#diff-3d9e6dc03ea37a4b7f7975db17f16509

Found in

gramps/gen/config.py

and

gramps/gui/grampsgui.py

Please note that in Gramps master this key is always True.

Release name

Refer to (and update) the list of previous releases.

Previously you needed to select an appropriate name but we have not named releases for several years now. You will still need to add the release though, including things like its relevant color.

Suggestions : For Gramps 5.0 Just remember that you're standing on a planet that's evolving

Changelog and NEWS file

Section 2a of the General Public License says that if you distribute a modified version of a program: you must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

Note that the 5.1.6 below means the previous version, not the one you're about to release (which is the ..).

git log v5.1.6.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
git log v5.1.6.. --pretty --numstat --summary --no-merges -- po/*.po | git2cl > po/ChangeLog
git add ChangeLog
git add po/ChangeLog

Edit and update the NEWS file using the new ChangeLog entries as a guide. If this is the first branch in a new series there will be no NEWS file, so look at a previous release and mimic the format.

Commit the NEWS file:

git add NEWS
git commit -m "Update Changelog and NEWS files"

Working on VERSION

Modify gramps/version.py to indicate an official release:

- DEV_VERSION = True
+ DEV_VERSION = False

Check that the VERSION_TUPLE reflects the release you're about to make. It should if the version was bumped after the last release. If not, fix it.

Save the changes:

git commit -am "Release Gramps 5.1.6"

Check that the version number is correct:

python3 Gramps.py -v

If everything looks good, push the changes:

 git push origin maintenance/gramps51

If that fails then someone pushed a commit while you were working. Return to Prepare your repository and start over.

Create a tag

Create the release tag; note the v leading the actual tag.:

git tag -am "Tag 5.1.6" v5.1.6

Push to repository

Push the changes to the repository:

git push origin v5.1.6

Move to the new release number on branch

Bump the version number in gramps/version.py

Update the version for the release:

VERSION_TUPLE = (4, 2, ...)

Revert change on DEV_VERSION so that the git revision is appended to the reported version in non-release builds:

- DEV_VERSION = False
+ DEV_VERSION = True

Save change:

git commit -am "Bump to <new version number>"
git push

Github

Github generates a tarball automatically when we push a tag.
Go to Github and log in if necessary.
Select NN Releases from the line of items just above the thick line (NN is the number of releases so far).
Find the tag you just pushed and click it, or click the "Draft a new release" button.
Copy the NEWS file contents into the Write tab. You can use the Preview tab to check your formatting.
Click Publish Release at the bottom of the edit area when you're satisfied with the contents.

SourceForge

Go to the SourceForge files page and log in if necessary.
Click on Stable or Unstable depending on the class of the release you're making.
Click Add Folder and name the directory for the release version. Click "'Create'". Click your new folder to enter it.
You can either download the GitHub-generated tarball or create one locally:

 python3 setup.py sdist

Click Add File and drag the tarball to the drop area on the web page.
Copy the release notes from GitHub into a file called README.md and upload it.

Announcing the new release

update mantisdb(Bug/issue database) and enable the new version via Admin:Projects item for reporting issues. (You will need a high-enough status on the bug tracker in order to do this, so you can ask an appropriate person if you aren't.)
announce on [email protected], [email protected] and [email protected] (You will need to be a member of all three lists first, to send to them.)
announce on the Discourse forum in the "Announcements" category.
announce on Gramps blog (File under: Gramps Releases and News) (not needed for an alpha or beta release)
update News section on this wiki (not needed for an alpha or beta release)
update the list of previous releases
update reference to the new version on the wiki template (not needed for an alpha or beta release)
Verify other "version" Wiki templates values: Last version, Stable version, etc.
update HeadlineNews (not needed for an alpha or beta release)
update release date on the Download page (not needed for an alpha or beta release)
change the Matrix room title and IRC channel title (not needed for an alpha or beta release)
update the version number at Wikipedia (not needed for an alpha or beta release)

Post-release

merge forward the NEWS file

External links

Difference between revisions of "What to do for a release"

Latest revision as of 22:18, 20 August 2023

Contents

Pre-release

Agree a release timetable

Announce a feature freeze

Translation update

Announce a string freeze

Prepare your repository

Check the About box year

API docs update year

Update Classifier in setup.py

Update the 'behavior.betawarn' key value

Release name

Changelog and NEWS file

Working on VERSION

Create a tag

Push to repository

Move to the new release number on branch

Github

SourceForge

Announcing the new release

Post-release

See also

External links

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Contributor help pages

wiki

Tools

@@ Line 1: / Line 1: @@
 {{man note|Developer notes for '''What to do for a release '''}}
-Note that the main use of this page will be for making
+Note that the main use of this page will be for making a normal "minor" release.  If you are making a "major" release (e.g. x.y.0) then you will need to update this page first, to change the numbers.  But if you are only making an "alpha" or "beta" release, some steps may be skipped, or altered slightly.
-a normal "minor" release.  If you are making a "major"
-release (e.g. x.y.0) then you will need to update this
-page first, to change the numbers.  But if you are only
-making an "alpha" or "beta" release, some
-steps may be skipped, or altered slightly.
-Note also that [[What_to_do_for_a_release#Post-release|Post release]]
+Note also that there are additional necessary [[What_to_do_for_a_release#Post-release|Post release]] tasks which are related to making a new release. For instance, the wiki will require making a new release-section and   updating [[Template:Version_Templates#General|"General" version templates]]. For the making a new release-section on the bug tracker. Or when making new Debian and Mac and Windows [[:Category:Developers/Packaging|packaging]], they will need to be coordinated with the appropriate [[Team#Package_Maintainers|package maintainers]] and updating the corresponding [[:Category:Versions|Versions]] : [[Template:Version_Templates|Templates]].
-there are additional things which need to be done,
-which are related to making a new release, for instance
+==Pre-release==
-making a new release-section here on the wiki, or
+===Agree a release timetable===
-making a new release-section on the bug tracker, or
-making new Debian and Mac and Windows packages, so
+Co-ordinate with the [[Team#Package_Maintainers|package maintainers]] to agree a release timetable.
-they will need to be coordinated with the appropriate
+For a major release there may be a schedule on the [[5.2_Roadmap|Roadmap]]
-people.
+===Announce a feature freeze===
+For a major release, announce a feature freeze on the ''gramps-devel'' mailing list.
+This will usually be about 4 weeks before the release date.
+===Translation update===
+The translation template should be updated, if necessary, just before the string freeze is announced.
+* Check for new files since the last release:
+  cd po
+  intltool-update -m
+:That will create a file called <code>missing</code>in the <code>po</code> directory if there are new files that need to be scanned for translatable strings. Examine each of the files listed in <code>missing</code>, adding each to <code>POTFILES.in</code> if it contains translatable string constants and to <code>POTFILES.skip</code> if it does not.
+* Generate a new template file:
+  python3 update_po.py -p # makes a new gramps.pot template file
+  git diff gramps.pot
+:Examine the changes. If they're all just comments about where a string is found you need not commit the change (so the next line will restore the official file, instead of the one you just made):
+  git restore gramps.pot
+:If there have been changes on <code>msgid</code> entries, you'll need to commit <code>gramps.pot</code> and ask translators to update their <tt>.po</tt> files before you can make a release:
+  git add gramps.pot
+  git commit -m "Update translation template for new release"
+* Check current translation files (there must be no 'fatal' errors):
+  python3 update_po.py -k all
+Also see:
+* [[Template:Gramps_translations#INCOMPLETE_TRANSLATIONS]] - Update if any translation needs to be added or excluded due to not meeting the minimum 70% completion requirement.
+===Announce a string freeze===
+For a major release, announce a string freeze on the ''gramps-devel'' mailing list and on Weblate.
+This will usually be about 2 weeks before the release date.
 ==Prepare your repository==
@@ Line 30: / Line 54: @@
 * Build and test to make sure that everything works, then clean the repo of all build products.
-==Translation update==
+===Check the About box year===
-* Check for new files since the last release:
-  cd po
+Check if the year in the {{man label|About}} box needs to be updated
-  intltool-update -m
-:That will create a file called <code>missing</code>in the <code>po</code> directory if there are new files that need to be scanned for translatable strings. Examine each of the files listed in <code>missing</code>, adding each to <code>POTFILES.in</code> if it contains translatable string constants and to <code>POTFILES.skip</code> if it does not.
+eg:
-* Generate a new template file:
+   ''© 2007-2021 The Gramps Developers''
-  python3 update_po.py -p # makes a new gramps.pot template file
+to
-  git diff gramps.pot
+   ''© 2007-'''2022''' The Gramps Developers''.
-:Examine the changes. If they're all just comments about where a string is found you need not commit the change (so the next line will restore the official file, instead of the one you just made):
-  git checkout gramps.pot
+Found in <code>gramps/gen/const.py</code>
-:If there have been changes on <code>msgid</code> entries, you'll need to commit <code>gramps.pot</code> and ask translators to update their <tt>.po</tt> files before you can make a release:
-  git add gramps.pot
+===API docs update year===
-  git commit -m "Update translation template for new release."
+If needed in the file:
+docs/conf.py
+Update the year for the copyright.
+ copyright = '2001-2022, The Gramps Project'
+===Update Classifier in setup.py===
+Change [https://pypi.python.org/pypi?%3Aaction=list_classifiers Classifier] to the appropriate one in [https://github.com/gramps-project/gramps/blob/maintenance/gramps50/setup.py setup.py]  (master is always the first one)
+<pre>
+Development Status :: 1 - Planning
+Development Status :: 2 - Pre-Alpha
+Development Status :: 3 - Alpha
+Development Status :: 4 - Beta
+Development Status :: 5 - Production/Stable
+</pre>
+Check if any additional language classifier needs to be added also.
+===Update the 'behavior.betawarn' key value===
+If the release is '''Production/Stable''' make sure that the '''behavior.betawarn''' key value has been set to '''False''' e.g., https://github.com/gramps-project/gramps/commit/9dc976f28dc16c514e9e8e0b0fa09338bfe04f8a#diff-3d9e6dc03ea37a4b7f7975db17f16509
+Found in
+ gramps/gen/config.py
+and
+ gramps/gui/grampsgui.py
-* Check current translation files (there must be no 'fatal' errors):
+Please note that in Gramps master this key is always '''True'''.
-  python3 update_po.py -k all
-* if all is well, return to the root directory:
+See also {{bug|11274}}
-  cd ..
 ==Release name==
-Refer to (and update) the [[Previous releases of Gramps|list of previous releases]].  Previously you needed to select an appropriate name but we have not named releases for several years now.  You will
+Refer to (and update) the [[Previous releases of Gramps|list of previous releases]].
-still need to add the release though, including things like its
-relevant color.
+Previously you needed to select an appropriate name but we have not named releases for several years now.  You will still need to add the release though, including things like its relevant color.
+* [[Talk:Previous_releases_of_Gramps|Suggestions]] : For Gramps 5.0 <code>Just remember that you're standing on a planet that's evolving</code>
 ==Changelog and NEWS file==
@@ Line 63: / Line 118: @@
   git log v{{version}}.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
   git log v{{version}}.. --pretty --numstat --summary --no-merges -- po/*.po | git2cl > po/ChangeLog
   git add ChangeLog
+ git add po/ChangeLog
 *Edit and update the <code>NEWS</code> file using the new ChangeLog entries as a guide. If this is the first branch in a new series there will be no NEWS file, so look at a previous release and mimic the format.
 Commit the NEWS file:
   git add NEWS
-  git commit -m "Update NEWS for {{version}} release"
+  git commit -m "Update Changelog and NEWS files"
 ==Working on VERSION==
+* Modify <code>[https://github.com/gramps-project/gramps/blob/master/gramps/version.py gramps/version.py]</code> to indicate an official release:
+ - DEV_VERSION = True
+ + DEV_VERSION = False
-* Check that the <code>VERSION_TUPLE</code> in <code>[https://github.com/gramps-project/gramps/blob/master/gramps/version.py gramps/version.py]</code>reflects the release you're about to make. It should if the version was bumped after the last release. If not, fix it.
+* Check that the <code>VERSION_TUPLE</code> reflects the release you're about to make. It should if the version was bumped after the last release. If not, fix it.
-* Modify <code>[https://github.com/gramps-project/gramps/blob/master/gramps/gen/const.py#L132 gramps/gen/const.py]</code> to indicate an official release:
- - VERSION += git_revision
- + #VERSION += git_revision
 * Save the changes:
@@ Line 85: / Line 141: @@
 * If everything looks good, push the changes:
    git push origin maintenance/gramps{{Stable_branch}}
-* If that fails then someone pushed a commit while you were working. Return to [https://gramps-project.org/wiki/index.php?title=What_to_do_for_a_release#Prepare_your_repository Prepare your repository] and start over.
+* If that fails then someone pushed a commit while you were working. Return to [[What_to_do_for_a_release#Prepare_your_repository|Prepare your repository]] and start over.
 ==Create a tag==
@@ Line 102: / Line 158: @@
   VERSION_TUPLE = (4, 2, ...)
-Revert change on <code>gramps/gen/const.py</code> so that the git revision is appended to the reported version in non-release builds:
+Revert change on <code>DEV_VERSION</code> so that the git revision is appended to the reported version in non-release builds:
-  - #VERSION += get_git_revision
+  - DEV_VERSION = False
-  + VERSION += get_git_revision
+  + DEV_VERSION = True
 Save change:
-  git commit -am "bump to <new version number>"
+  git commit -am "Bump to <new version number>"
   git push
@@ Line 114: / Line 170: @@
 * Go to [https://github.com/gramps-project/gramps Github] and log in if necessary.
 * Select '''NN Releases''' from the line of items just above the thick line ('''NN''' is the number of releases so far).
-* Find the tag you just pushed and click Edit.
+* Find the tag you just pushed and click it, or click the "Draft a new release" button.
 * Copy the NEWS file contents into the '''Write''' tab. You can use the '''Preview''' tab to check your formatting.
 * Click '''Publish Release''' at the bottom of the edit area when you're satisfied with the contents.
@@ Line 122: / Line 178: @@
 * Click on '''Stable''' or '''Unstable''' depending on the class of the release you're making.
 * Click '''Add Folder''' and name the directory for the release version. Click "'Create'". Click your new folder to enter it.
-* You can either download the Github-generated tarball or create one locallly:
+* You can either download the GitHub-generated tarball or create one locally:
    python3 setup.py sdist
 * Click '''Add File''' and drag the tarball to the drop area on the web page.
+* Copy the release notes from GitHub into a file called README.md and upload it.
 ==Announcing the new release==
 * update mantisdb(Bug/issue database) and enable the new version via Admin:Projects item for reporting issues. (You will need a high-enough status on the bug tracker in order to do this, so you can ask an appropriate person if you aren't.)
 * announce on [email protected], [email protected] and [email protected] (You will need to be a member of all three lists first, to send to them.)
-* announce on Gramps [https://gramps-project.org/introduction-WP/blog/ blog] (File under: [https://gramps-project.org/introduction-WP/category/releases/ Gramps Releases] and [https://gramps-project.org/introduction-WP/category/news/  News]) (not needed for an alpha or beta release)
+* announce on the Discourse forum in the "[https://gramps.discourse.group/c/gramps-announce Announcements]" category.
+* announce on Gramps [https://gramps-project.org/blog/blog/ blog] (File under: [https://gramps-project.org/blog/category/releases/ Gramps Releases] and [https://gramps-project.org/blog/category/news/  News]) (not needed for an alpha or beta release)
 * update [[News]] section on this wiki (not needed for an alpha or beta release)
 * update the list of [[Previous releases of Gramps|previous releases]]
 * update reference to the new version on the [[Template:Version|wiki template]] (not needed for an alpha or beta release)
+* Verify other [[:Category:Versions|"version" Wiki templates]] values: Last version, Stable version, etc.
 * update [[HeadlineNews]] (not needed for an alpha or beta release)
-* change the topic on the IRC channel #gramps (not needed for an alpha or beta release)
+* update release date on the [[Download]] page (not needed for an alpha or beta release)
-<code> /TOPIC #gramps Welcome to Gramps! The latest versions are {{version}} and the legacy 3.4.9 || http://www.gramps-project.org/ || Please state OS and Gramps version when asking a question. Understand that replies can take up to 2 days depending on whose watching the channel. Please consider asking on the gramps-users mailing list. </code>
+* change the Matrix room title and IRC channel title (not needed for an alpha or beta release)
-* update the version number at [http://en.wikipedia.org/wiki/Gramps Wikipedia] (not needed for an alpha or beta release)
+* update the version number at [https://en.wikipedia.org/wiki/Gramps_(software) Wikipedia] (not needed for an alpha or beta release)
 ==Post-release==
@@ Line 142: / Line 201: @@
 =See also=
+*Category [[:Category:Versions|Versions]] : [[Template:Version_Templates|Template]]
+*Building a distribution to share as on the [[Download]] page
+:[[File:Windows_32x32.png]] [[Building Gramps AIO cx freeze-based]] - Updating the MS-Windows 32-bit and 64-bit All-In-One packages
+<!--
+:[[File:Linux 32x32.png]]   please add link to instructions on building Gramps installers for Linux. proofed while building v5.1.3
+:[[File:Beastie 32x32.png]]   please add link to instructions on building Gramps installer for BSD. proofed while building v5.1.3
+:[[File:Apple logo black 32x32.png]]   please add link to instructions on building Gramps installer for Apple. proofed while building v5.1.3
+-->
 * [[Brief introduction to Git]]
 * [[Running a development version of Gramps]]
 * [[:Category:Developers/Packaging]]
-* [[GrampsAIO-4 package updating]] - Updating the MS-Windows package
 * [[:Category:AppData]] - Screenshots used by Appdata - Debian
+* [[.dtd and .rng]]
+* [[Rollover_for_the_manual|Rollover for the Wiki]] - for major and minor releases. No rollover for maintenance releases.
+* [[Special:WhatLinksHere/Template:Bug|List of pages linked to Bug Report template]] - verify the reported issues still apply to the new release. Leave links in place for any issue fixed in maintenance releases. Simply add notations for the version where the fix was applied. Remove links for fixed issues in Rollovers.
 =External links=
 * https://github.com/gramps-project
-* http://gramps-project.org/cpanel
+* https://gramps-project.org/cpanel
-* http://sourceforge.net/projects/gramps/
+* https://sourceforge.net/projects/gramps/
 [[Category:Developers/General]]
+[[Category:Developers/Packaging]]