[GRASS5] Fertilizer 2002: CVS and release strategies

GRASS GRASS developer
1

  GRASS-Development Meeting 24.11.2001 Trento 2001
  ================================================

In the late evening Markus, Bernhard and Radim
managed to have a small meeting about GRASS development strategy.

This texts summarises Bernhard's ideas about how
to handle the CVS and releases. Radim contributed the
first proposal of what to call a release critical bug
and which CVS tree and branch to choose to work on.

The symptoms:
  We do not release tar balls frequently enough.
  The long needed 5.0 stable release has not happened yet.

Conclusion:
  The stable release will come when it is ready.
  If critical bugs continue to be found
  a tarball cannot be called stable.

  GRASS development has to be more strict about
  the process of handling CVS branches, reparing tarballs
  and fixing bugs. The group of developers is growing.
  Only if we repeat certain steps with more discipline
  and build more structure the trust in the process will grow.

Details:

You will find a addendum at the end of this text
with proposals for CVS terminology, what constitutes a critical bug
and CVS commit rules.

    The development tree
    --------------------

The grass51 tree in the CVS is not utilised enough.
Developers should have more courage to just utilise it.
As this is clearly a development tree, there is no problem
to just start away with the new structure.
The 5.1.x series will lead to the 5.2.x stable line.
Until then, developers can reorganise things as much as they want.
All developers interested in progressing grass and really cleaning
it up should just go ahead. We can only learn from the attempts.

The new development tree does not necessarily need to include all
radical changes we can think of at once. Development should leave
major problems without a good new approach for 5.3.x.

Radim pointed out that he needs old functionality to test the new vector
implementation which is not transfered to the grass51 structure yet.
Thus it is reasonable if you need to have a known version of the
5.0.x source around to test it until the functions are included into
5.1.x. Preferable is a recent tarball release or a tagged version from the CVS.
Make sure that there is a script and clear instructions to
merge, compile and test the new code.

    The stable tree
    ---------------

Developers cannot wait with a release until the last bug is fixed.
Software will always have bugs. Even versions rightfully called stable.
The goal is to release a tarball which does not have critical problems.

On the other hand there will always be normal bugs, minor cleanup and
important feature requests that are best suited to go into the 5.0.x series.

Some developers are working on the former, some on the latter.
Thus we can use CVS branches to make sure that development can
continue parallel most of the time. The idea is to have a release
branch which only includes modules that have the quality to be
released. We release this branch as a tarball labeled "prex".
Within a fixed period of time like 5 weeks we then decide
to fully release it or make another "prex+1" release.
Then we merge back. If the time is too long, we might merge back
anyway to sync the stable tree.

If we need to release important extra modules not being stable yet
we can make a tarball containing "unstable" modules having various
problems.

The described strategy has been already tried, but not strictly enough.
Developers have to resist the temptation to fix
non-release critical bugs in the release branch.
This should not be a problem if we manage to have more frequent
tarball releases, even if they are only "pre" releases.

   Identifying "critical bugs" and managing the cycle:

The bugtracker has to be utilised to document the progress
on bugs. A priority of 70 or greater should equal critical
for release now.

GRASS development could need a person to manage the release
cylcle. The firsts tasks of the "release manager" would be to watch
the time frame and ask back about release critical bugs.
A great advantage is that you do not need developers skills to help
with this. Please send mail to the grass5 list, if you are
interested to help Markus with this.

   "The making of" a GRASS-tarball
   -------------------------------

Markus raised the issue that it is about one working day for him
to release a grass version as tarball. This process has to be easier
for him. Thus the following was suggested by Bernhard:

  a) Markus will only release source tarball.

  b) The tarballs will announced to helpers and alphatesters
  one week in advance so there is a change to build binaries.
  If binaries will not be produced the release will
  be announced anyway.

  c) There will be a scripts so that binaries can be build
  automatically.
  
  d) Scripts can make changed to the webpages easier.
  Volenteers are need to help with the pages.

It is necessary to give a time frame and stick to it.
If not enough people can be found to test "pre" releases or
create binaries in time, we have to consider that there is less
interest in the functionality in question or the ports.
Generally it is not in the resonsibility of Markus to make sure
that we support all available combinations of hardware and software.

    Next steps
    ----------

Markus and Bernhard already managed to check in the webpages of
GRASS into the CVS and put a script in place which will update them
once a day or triggered by Markus. This is a first step with d).
Any developer with CVS write access can directly help with the webpages now.

The april release branch existed too long.
We have to merge it back as soon as possible.
Markus plans to have another 5.0.0pre4 release which would not
follow the strategy outlined above for transitional reasons.
There will be at least one other release branch and a 5.0.0pre5
before the 5.0.0 release. Pre5 has to be aimed for as fast as possible.

Andreas already started a script to build grass binaries.

Please identify the release critical bugs.

Do not hestitate to start experiments to just
build the new structure for in the development tree grass51.
Inform the grass5 list of your changes, though.

14.1.2002 Bernhard <bernhard@intevation.de>

Addendum

    CVS terminology
    ---------------

There are three levels where CVS keeps code:
repositories, trees and branches.
In CVS terminology, a module or tree is a seperate independent entry
in the repository. It has a path on its own.
Then you can have several branches on the trees.

There is one GRASS repository, running on a Server in Osnabrück right now.
It contains the following modules:
  grass grass51 libgrass programmgrass50 web

So there are two trees for grass code right now:
  "grass" and "grass51".
The "grass" tree usually has two branches.

This text proposes to use the following names:

trees:
  grass stable tree
  grass51 development tree

branches:
  grass or stable tree:
    release branch scheduled for release
    main branch

  grass51 or development tree:
    development branch for all branches
    
    Release Critical Bugs
    ----------------------

A bug is critical, when it
   * makes unrelated software on the system (or the whole system) break, or
      causes serious data loss, or introduces a security hole on systems where
      you install the package.
   * makes GRASS unuseable or mostly so, or causes data loss,
      or introduces a security hole
   * is a believed to be critical by the coordinator of the release

A bug is not critical, when it
   * appeares on certain circumstances only (platform, data) and
      is described in 'Known bugs' section on manual page.

    Rules for committing to branches on stable tree
    -----------------------------------------------

* Only 'release critical bugs' may be commited to the current release branch

* Each change commited to the release branch must be immediately
   commited to the main branch. If change in stable branch was
   not commited to development branch, developer will be asked to do that
   via mailing list.

* If new feature or fix which does not fix a release critical bug
   was commited to the current release branch, author will be asked
   to revert to previous version via mailing list.

19.1.20002 Bernhard Reiter and Radim Blazek

--
Professional Service around Free Software (intevation.net)
The FreeGIS Project (freegis.org)
Association for a Free Informational Infrastructure (ffii.org)
FSF Europe (fsfeurope.org)

2

Bernhard Reiter wrote:

* Each change commited to the release branch must be immediately
   commited to the main branch. If change in stable branch was
   not commited to development branch, developer will be asked to do that
   via mailing list.

This isn't always as straightforward as the preceding paragraph
implies.

If someone has been modifying the corresponding program/library on the
development branch (trunk), a fix which works for the stable version
may not work on (or even apply to) the development version. If the
development version has changed significantly and/or is in a state of
flux, someone who can produce a fix for the stable version might not
be able to determine a suitable fix for the development version.

--
Glynn Clements <glynn.clements@virgin.net>

3

On Sun, Jan 20, 2002 at 02:03:44AM +0000, Glynn Clements wrote:

Bernhard Reiter wrote:

> * Each change commited to the release branch must be immediately
> commited to the main branch. If change in stable branch was
> not commited to development branch, developer will be asked to do that
> via mailing list.

This isn't always as straightforward as the preceding paragraph
implies.

True.
Still, if you fix a release critical bug on the _release_ branch
you should make sure that the bug is fixed in the _main_ branch.
This might be a different fix, though.

If someone has been modifying the corresponding program/library on the
development branch (trunk),

Please call it "main" branch, as it might be confused with the
"development" tree to easily otherwise.

a fix which works for the stable version
may not work on (or even apply to) the development version.

The release branch should never be far away from the main branch
on the stable tree.

If the
development version has changed significantly and/or is in a state of
flux, someone who can produce a fix for the stable version might not
be able to determine a suitable fix for the development version.

It has to be tried, though.

4

On Sat, Jan 19, 2002 at 11:29:05PM +0100, Bernhard Reiter wrote:

Markus raised the issue that it is about one working day for him
to release a grass version as tarball. This process has to be easier
for him. Thus the following was suggested by Bernhard:

  a) Markus will only release source tarball.

Markus, etc,

I can understand that producing a release can be a substantial amount of
work for something as large and complicated as GRASS. I just wanted to
suggest one procedure that has helped me. I now keep a HOWTO-RELEASE
file in each of my projects which lists the set of things I must do each
release.

In theory this is mainly to make it easier for someone else to do a release
if I should be hit by a truck or something. However, I also find I can
produce a source release substantially quicker with a detailed set of notes
on what needs to be done. It also makes sure all the "release specific"
information gets updated properly.

I have attached my HOWTO-RELEASE from PROJ.4 as an example.

I think it would be helpful to have something similar for GRASS.

Best regards,

--
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam@pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | Geospatial Programmer for Rent

  Preparing a PROJ.4 Release
  ==========================

1) Update the version number in configure.in (in AM_INIT_AUTOMAKE()).

2) Update the version number in proj_api.h (#define PJ_VERSION).

3) Update the version number, and date in src/pj_release.c.

4) Update the version number in the -version-info definition in
   src/Makefile.am. It consists of "current:revision:age".

   - If the library source code has changed at all since the last update,
     then increment revision (c:r:a becomes c:r+1:a).

   - If any interfaces have been added, removed, or changed since the last
     update, increment current, and set revision to 0.

   - If any interfaces have been added since the last public release, then
     increment age.

   - If any interfaces have been removed since the last public release, then
     set age to 0.

5) Add a note to the ChangeLog that a new release is being issued, and what
   the release number is.

6) Tag the release with a command like "cvs tag proj_4_4_3".

7) Do a "make dist-all" in the proj root directory. After some grinding
   this should result in files like proj-4.4.3.tar.gz and proj-4.4.3.zip
   being created. These are full source distributions.

8) Put these in the proj ftp area on ftp.remotesensing.org. This can be
   done via scp using a command like the following.

     scp proj-4.4.3.{tar.gz,zip} remotesensing.org:/ftp/remotesensing/pub/proj

9) Update html/index.html to link to the new release tar/zip files. When
   committed this updates the web page on remotesensing.org.

10) Announce the new release on the PROJ.4 mailing lists. If the release
   is particularly significant in terms of features it might also be
   announced in comp.infosystems.gis, os-remotesensing@remotesensing.org,
   and freegis-list@intevation.de.

11) Issue a new release report on Freshmeat.

   http://freshmeat.net/projects/proj.4/

NOTES:

o Information about preparing binary releases, and RPMs should be formalized.
o A "beta" release step should likely be incorporated.

5

On Mon, Jan 21, 2002 at 09:30:41AM -0500, Frank Warmerdam wrote:

On Sat, Jan 19, 2002 at 11:29:05PM +0100, Bernhard Reiter wrote:
> Markus raised the issue that it is about one working day for him
> to release a grass version as tarball. This process has to be easier
> for him. Thus the following was suggested by Bernhard:
>
> a) Markus will only release source tarball.

Markus, etc,

I can understand that producing a release can be a substantial amount of
work for something as large and complicated as GRASS. I just wanted to
suggest one procedure that has helped me. I now keep a HOWTO-RELEASE
file in each of my projects which lists the set of things I must do each
release.

In theory this is mainly to make it easier for someone else to do a release
if I should be hit by a truck or something. However, I also find I can
produce a source release substantially quicker with a detailed set of notes
on what needs to be done. It also makes sure all the "release specific"
information gets updated properly.

I have attached my HOWTO-RELEASE from PROJ.4 as an example.

I think it would be helpful to have something similar for GRASS.

thanks a lot, Frank. I have seen recently that you added the file to the
PROJ.4 repository. Luckily I have already written such a file for GRASS:
http://freegis.org/cgi-bin/viewcvs.cgi/~checkout~/grass/documents/release_rules.txt?rev=1.22.2

As it won't be perfect and partly confusing, I encourage all
to submit comments or fix it directly in CVS.

I'll browse your HOWTO and borrow further ideas,
thanks again,

Markus

6

It's so quiet here...
Everybody still chewing on the text?

I think it is important that te majority of developers
at least comments briefly.

On Sat, Jan 19, 2002 at 11:29:05PM +0100, Bernhard Reiter wrote:

  GRASS-Development Meeting 24.11.2001 Trento 2001
  ================================================

In the late evening Markus, Bernhard and Radim
managed to have a small meeting about GRASS development strategy.

This texts summarises Bernhard's ideas about how
to handle the CVS and releases. Radim contributed the
first proposal of what to call a release critical bug
and which CVS tree and branch to choose to work on.

The symptoms:
  We do not release tar balls frequently enough.
  The long needed 5.0 stable release has not happened yet.

Conclusion:
  The stable release will come when it is ready.
  If critical bugs continue to be found
  a tarball cannot be called stable.

  GRASS development has to be more strict about
  the process of handling CVS branches, reparing tarballs
  and fixing bugs. The group of developers is growing.
  Only if we repeat certain steps with more discipline
  and build more structure the trust in the process will grow.