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

From Gramps
Jump to: navigation, search
m (Guidelines for version 4.0)
m (Announcing the new release)
 
(186 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''What to do for a release '''
+
{{man note|Developer notes for '''What to do for a release '''}}
= Guidelines for version 4.0 =
 
  
These notes are based on version 4.0.0alpha1, released in December 2012The steps assume a working <tt>gramps40</tt> source directory.
+
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 numbersBut if you are only
 +
making an "alpha" or "beta" release, some
 +
steps may be skipped, or altered slightly.
  
==Translation update==
+
Note also that
Run the following steps:
+
there are additional things which need to be done,
cd gramps40
+
which are related to making a new release, for instance
svn update
+
making a new release-section here on the wiki, or
cd po
+
making a new release-section on the bug tracker, or
python update_po.py -p # or intltool-update -p , .genpot.sh see [[Translation_environment4|New environment]]
+
making new Debian and Mac and Windows packages, so
svn diff gramps.pot
+
they will need to be coordinated with the appropriate
If there have been changes, you'll need to commit <tt>gramps.pot</tt> and ask translators to update their <tt>.po</tt> files before you can make a release.
+
people. Probably there should be a section of this
 +
page which lists things like that ("Post-release" maybe?).
  
==Release name==
+
==Prepare your repository==
Refer to (and update) the [[Previous releases|list of previous releases]] to select an appropriate name.
+
* Check out the current stable branch:
 +
  git checkout maintenance/gramps{{Stable_branch}}
 +
:That branch name assumes that you're using the same name as the Github repository; if you're not (perhaps you don't use <code>maintenance</code> 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.
  
==Changelog and NEWS file==
+
==Translation update==
Create the changelog files:
+
* Check for new files since the last release:
svn2cl --reparagraph --include-rev --authors=gramps/data/authors.xml
+
  cd po
cd po
+
  intltool-update -m
svn2cl --reparagraph --include-rev --authors=../gramps/data/authors.xml
+
: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.
cd ..
+
* 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 checkout 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."
  
Using the <tt>Changelog</tt> files generated with <tt>svn2cl</tt> in the step above, edit and update the <tt>NEWS</tt> file.
+
* Check current translation files (there must be no 'fatal' errors):
Commit the NEWS file.  Note the svn commit revision number, which you'll need in the next step when you create the subversion tag:
+
  python3 update_po.py -k all
svn commit -m "update for 4.0.0-alpha1 release"
 
Committed revision 20810.
 
  
==Working on VERSION==
+
* if all is well, return to the root directory:
 +
  cd ..
  
Modify <tt>setup.py</tt> to indicate an official release:
+
==Release name==
gedit setup.py
+
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 nowYou will
and update the version for the release:
+
still need to add the release though, including things like its
VERSION = "4.0.0-alpha1"
+
relevant color.
Save change.
 
  svn commit -m "make official release" setup.py
 
The version number should be the same on "about" dialog:
 
python Gramps.py
 
  
==Subversion tag==
+
==Changelog and NEWS file==
Using the previous commit revision number, create a tag for the new release:
 
svn copy -r 20810 https://svn.code.sf.net/p/gramps/code/branches/maintenance/gramps40 https://svn.code.sf.net/p/gramps/code/tags/gramps-4.0.0-alpha1 -m "tag 4.0.0 alpha1"
 
Committed revision 20811.
 
  
==Changelog and source tarball==
+
[https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html#section2 Section ''2a''] of the '''G'''eneral '''P'''ublic '''L'''icense 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''.  
The Changelog files are required for the source tarball, but do not commit to subversion:
 
svn2cl --reparagraph --include-rev --authors=gramps/data/authors.xml
 
cd po
 
svn2cl --reparagraph --include-rev --authors=../gramps/data/authors.xml
 
cd ..
 
Create the official source tarball:
 
python setup.py sdist
 
  
Note you should now have the file <tt>dist/gramps-4.0.0-alpha1.tar.gz</tt>, approximately 12.2 Mo in size.
+
Note that the <code>{{version}}</code> below means the ''previous'' version, not the one you're about to release (which is the
 +
<code>..</code>).
 +
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
 +
*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"
  
==Making the source tarball available==
+
==Working on VERSION==
* access the "Sourceforge Project Admin->File Manager" page at https://sourceforge.net/projects/gramps/
 
* create a new folder in the "Unstable" hierarchy
 
* upload the <tt>gramps-*.tar.gz</tt> file to the new folder
 
  
==Announcing the new release==
+
* 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.
* announce on gramps-announce@lists.sourceforge.net, gramps-devel@lists.sourceforge.net and gramps-users@lists.sourceforge.net
+
* update [[News]] section on this wiki
+
* 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:
* update the list of [[previous releases]]
+
- VERSION += git_revision
* update reference to the new version on the [[Template:Version|wiki template]]
+
+ #VERSION += git_revision
* change the topic on the IRC channel #gramps
 
* update the version number at [http://en.wikipedia.org/wiki/GRAMPS Wikipedia]
 
  
==Post-release==
+
* Save the changes:
* in <tt>trunk</tt>, merge forward the <tt>NEWS</tt> file
+
git commit -am "Release Gramps {{version}}"
  
= Guidelines for version 3.4 and before =
+
* Check that the version number is correct:
These notes are based on version 3.4.1, released in August 2012. The steps assume a working <tt>gramps34</tt> source directory.
+
  python3 Gramps.py -v
  
==Translation update==
+
* If everything looks good, push the changes:
Run the following steps:
+
  git push origin maintenance/gramps{{Stable_branch}}
cd gramps34
+
* 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.
svn update
 
cd po
 
make gramps.pot
 
svn diff gramps.pot
 
If there have been changes, you'll need to commit <tt>gramps.pot</tt> and ask translators to update their <tt>.po</tt> files before you can make a release.
 
  
==Release name==
+
==Create a tag==
Refer to (and update) the [[Previous releases|list of previous releases]] to select an appropriate name.
+
Create the release tag; note the '''v''' leading the actual tag.:
 +
git tag -am "Tag {{version}}" v{{version}}
  
==Changelog and NEWS file==
+
==Push to repository==
Create the changelog files:
+
Push the changes to the repository:
  svn2cl --reparagraph --include-rev --authors=src/data/authors.xml
+
  git push origin v{{version}}
cd po
 
svn2cl --reparagraph --include-rev --authors=../src/data/authors.xml
 
cd ..
 
  
Using the <tt>Changelog</tt> files generated with <tt>svn2cl</tt> in the step above, edit and update the <tt>NEWS</tt> file.
+
===Move to the new release number on branch ===
Commit the NEWS file.  Note the svn commit revision number, which you'll need in the next step when you create the subversion tag:
 
svn commit -m "update for 3.4.1 release"
 
Committed revision 20254.
 
  
==Subversion tag==
+
Bump the version number in <code>gramps/version.py</code>
Using the previous commit revision number, create a tag for the new release:
 
svn copy -r 20254 https://svn.code.sf.net/p/gramps/code/branches/maintenance/gramps34 https://svn.code.sf.net/p/gramps/code/tags/gramps-3.4.1 -m "tag 3.4.1"
 
Committed revision 20255.
 
  
==Working on the tag==
+
Update the version for the release:
Check out the new tag:
+
  VERSION_TUPLE = (4, 2, ...)
  cd ..
 
svn co https://svn.code.sf.net/p/gramps/code/tags/gramps-3.4.1
 
cd gramps-3.4.1
 
  
Modify <tt>configure.in</tt> to indicate an official release:
+
Revert change on <code>gramps/gen/const.py</code> so that the git revision is appended to the reported version in non-release builds:
gedit configure.in
+
  - #VERSION += get_git_revision
There are two changes to make:
+
  + VERSION += get_git_revision
:1) Change the following line:
 
  -RELEASE=0.SVN$(svnversion -n .)
 
  +dnl RELEASE=0.SVN$(svnversion -n .)
 
:2) And change this line:
 
-dnl RELEASE=1
 
+RELEASE=1
 
Save these two changes.
 
svn commit -m "make official release" configure.in
 
Now run the following and check the version number in the "about" dialog:
 
./autogen.sh
 
make
 
python src/gramps.py
 
  
==Changelog and source tarball==
+
Save change:
Re-create (or copy from above) the 2 Changelog files. The Changelog files are required for the source tarball, but do not commit to subversion:
+
  git commit -am "bump to <new version number>"
svn2cl --reparagraph --include-rev --authors=src/data/authors.xml
+
  git push
cd po
 
svn2cl --reparagraph --include-rev --authors=../src/data/authors.xml
 
cd ..
 
Create the official source tarball:
 
  make distcheck
 
  
Note you should now have the file <tt>gramps-3.4.1.tar.gz</tt>, approximately 9.6 Mo in size.
+
===Github===
 +
* Github generates a tarball automatically when we push a tag.
 +
* 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.
 +
* 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.
  
==Making the source tarball available==
+
===SourceForge===
* access the "Sourceforge Project Admin->File Manager" page at https://sourceforge.net/projects/gramps/
+
* Go to [https://sourceforge.net/projects/gramps/files/ the SourceForge files page] and log in if necessary.
* create a new folder in the "Stable" hierarchy
+
* Click on '''Stable''' or '''Unstable''' depending on the class of the release you're making.
* upload the <tt>gramps-*.tar.gz</tt> file to the new folder
+
* 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:
 +
  python3 setup.py sdist
 +
* Click '''Add File''' and drag the tarball to the drop area on the web page.
  
 
==Announcing the new release==
 
==Announcing the new release==
* announce on gramps-announce@lists.sourceforge.net, gramps-devel@lists.sourceforge.net and gramps-users@lists.sourceforge.net
+
* 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.)
* update [[News]] section on this wiki
+
* announce on gramps-announce@lists.sourceforge.net, gramps-devel@lists.sourceforge.net and gramps-users@lists.sourceforge.net (You will need to be a member of all three lists first, to send to them.)
* update the list of [[previous releases]]
+
* 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)
* update reference to the new version on the [[Template:Version|wiki template]]
+
* update [[News]] section on this wiki (not needed for an alpha or beta release)
* change the topic on the IRC channel #gramps
+
* update the list of [[Previous releases of Gramps|previous releases]]
* update the version number at [http://en.wikipedia.org/wiki/GRAMPS Wikipedia]
+
* update reference to the new version on the [[Template:Version|wiki template]] (not needed for an alpha or beta release)
 +
* 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)
 +
<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>
 +
* update the version number at [http://en.wikipedia.org/wiki/Gramps Wikipedia] (not needed for an alpha or beta release)
  
 
==Post-release==
 
==Post-release==
* in <tt>gramps34</tt>, bump the version number in <tt>configure.in</tt> and <tt>src/const.py.in</tt>
+
* merge forward the <code>NEWS</code> file
* in <tt>trunk</tt>, merge forward the <tt>NEWS</tt> file
 
  
 
=See also=
 
=See also=
* [[Brief introduction to SVN]]
+
* [[Git|Brief introduction to Git]]
 
* [[Running a development version of Gramps]]
 
* [[Running a development version of Gramps]]
 
* [[:Category:Developers/Packaging]]
 
* [[:Category:Developers/Packaging]]
 +
* [[GrampsAIO-4 package updating]] - Updating the MS-Windows package
 +
* [[:Category:AppData]] - Screenshots used by Appdata - Debian
  
 
=External links=
 
=External links=
 +
* https://github.com/gramps-project
 +
* http://gramps-project.org/cpanel
 
* http://svn.code.sf.net/p/gramps/code/
 
* http://svn.code.sf.net/p/gramps/code/
* http://gramps-project.org/cpanel
 
 
* http://sourceforge.net/projects/gramps/
 
* http://sourceforge.net/projects/gramps/
  
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]

Latest revision as of 04:13, 23 September 2017

Gramps-notes.png
'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 things which need to be done, which are related to making a new release, for instance making a new release-section here on the wiki, or making a new release-section on the bug tracker, or making new Debian and Mac and Windows packages, so they will need to be coordinated with the appropriate people. Probably there should be a section of this page which lists things like that ("Post-release" maybe?).

Prepare your repository

  • Check out the current stable branch:
 git checkout maintenance/gramps42
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.

Translation update

  • 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 checkout 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
  • if all is well, return to the root directory:
 cd ..

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.

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 4.2.6 below means the previous version, not the one you're about to release (which is the ..).

git log v4.2.6.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
git log v4.2.6.. --pretty --numstat --summary --no-merges -- po/*.po | git2cl > po/ChangeLog
git add 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 NEWS for 4.2.6 release"

Working on VERSION

  • Check that the VERSION_TUPLE in gramps/version.pyreflects the release you're about to make. It should if the version was bumped after the last release. If not, fix it.
- VERSION += git_revision
+ #VERSION += git_revision
  • Save the changes:
git commit -am "Release Gramps 4.2.6"
  • Check that the version number is correct:
python3 Gramps.py -v
  • If everything looks good, push the changes:
 git push origin maintenance/gramps42
  • 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 4.2.6" v4.2.6

Push to repository

Push the changes to the repository:

git push origin v4.2.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 gramps/gen/const.py so that the git revision is appended to the reported version in non-release builds:

- #VERSION += get_git_revision
+ VERSION += get_git_revision

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 Edit.
  • 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 locallly:
 python3 setup.py sdist
  • Click Add File and drag the tarball to the drop area on the web page.

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 gramps-announce@lists.sourceforge.net, gramps-devel@lists.sourceforge.net and gramps-users@lists.sourceforge.net (You will need to be a member of all three lists first, to send to them.)
  • 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)
  • 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)

/TOPIC #gramps Welcome to Gramps! The latest versions are 4.2.6 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.

  • update the version number at Wikipedia (not needed for an alpha or beta release)

Post-release

  • merge forward the NEWS file

See also

External links