gnustep-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Versioning/release policy proposal


From: Adam Fedor
Subject: Re: Versioning/release policy proposal
Date: Sat, 21 Oct 2006 20:16:27 -0600

Most people seem to agree with this, as well as I. Plus it appears to roughly follow Helge's suggestions (although I admit I'm confused by that still). Anyway, I've added this in slightly edited form to our release policy:

http://wiki.gnustep.org/index.php/GNUstep_release_policy


On Oct 5, 2006, at 4:28 AM, Richard Frith-Macdonald wrote:


This is a proposal for conventions to be adopted for releasing 
GNUstep packages ... the idea being that something like this could be 
added to our FAQ and used as a reference for making releases and to 
some extent guiding what changes we allow into trunk in SVN.

I'm CC'ing this to the developer list for information purposes, but I 
lack the time to respond to comments directly (especially if this 
gets a lot of flaming etc) other than those from GNUstap 
maintainers.  I'm aware that not everyone can be pleased. but I've 
made my best attempt to satisfy people, and I'm hoping that Adam, 
Gregory and Nicola will broadly agree and add any final polish taking 
any other opinions into account.



1. Release Version Numbering scheme
We retain the current major.minor.subminor version numbering scheme 
for releases and for naming tags in svn.
eg. when making a release of version 1.2.3 of package foo the svn tag 
is foo_1_2_3.
This is clear, conventional, and well understood.

2. Library Version Numbering scheme
We retain the current link between release versions and library 
(SONAME) versions ... in that changing the major or minor version 
number of a release also implies changing the library version number, 
but changing the subminor number does not.  So release 1.2.3 of 
package foo implies library libfoo.so.1.2 as does
release 1.2.4 etc.  This provides a clear and simple link between 
release version and library version while allowing us to make 
releases without having to change the library version we expect apps 
to link to.

3. Policy on changing version numbers
We change the minor version number (and therefore the library 
version) when we break backward compatibility .  This will mean that 
most releases we make will only change the subminor number rather 
than the minor number even where we have added substantial new 
features.  While I realise that this has a problem with public 
perception being that the project is dead because it never makes 
'big' new releases, I think it's better to address the problem with 
improved publicity of what's in the new release rather than by hoping 
that a big version number change will do it for us.  On the rare 
occasion where we want a big public change, we would change the major 
version number (and of course SONAME).

4. Release stability policy
We advertise a 'stable' release *every* time we break backward 
compatibility.  Doing this requires making two releases pretty much 
at the same time and bumping the minor version number for each.  Eg. 
if the last release was 1.3.24 then we release 1.4.0 as 'stable' and 
1.5.0 as 'unstable', each with the appropriate change in the SONAME.  
All releases (if any) in the 1.4 family would be bugfix releases.
I suspect the vast majority of people would just use the 'unstable' 
releases (largely defeating the point of having 'stable' ones), but 
the overhead of doing a 'stable' release is very low, so I don't see 
why we shouldn't do it.
We can make 'stable' releases be those with even subminor version 
numbers.

5. Standard release procedure (backward compatible with previous 
version)
a. tag the version for release using the name_major_minor_subminor 
convention.
b. make tarballs and installation packages
c. bump the subminor version number in trunk
d. put release on ftp site and publicise

5. Standard release procedure (NOT backward compatible with previous 
version)
a. bump the minor version number and SONAME and reset the subminor 
number to zero
b. tag the version for release as 'stable' using the 
name_major_minor_subminor convention.
c. make tarballs and installation packages
d. bump the minor version number and SONAME and reset the subminor 
number to zero
e. tag the version for release as 'unstable' using the 
name_major_minor_subminor convention.
f. put releases on ftp site and publicise

6. Bugfix release procedure
a. if this is the first bugfix release of a package version, make a 
branch from the tagged release using the tag name as the branch name
eg. if the release was tagged in svn as foo/tags/foo_1_2_0 then the 
branch is foo/branches/foo_1_2_0
b. apply bugfixes to the branch
c. tag the branch as foo_1_2_0-1
d. make tarballs and installation packages
e. put on ftp site and publicise
NB.  we only ever make 'bugfix' releases in 'stable' release 
families, and these are the only sort of releases we make in those 
families.

7. Breaking backward compatibility
We should continue to strive to avoid this.   There are basically two 
areas to address.

First: changes to public ivar layout
This is painful ... we must continue to collect such changes together 
and do them very infrequently.
We should code to avoid this altogether, by clever re-use of wasted 
space in existing ivar layouts or by storing information in 
additional map tables so that ivars don't need to change 
(inefficient, but ok as a temporary measure so that actual changes to 
the ivars of classes can be very infrequent).

Second:  removal of public variables, functions, methods, classes etc.
We must do this in an organised manner ... features *must* be 
deprecated before removal.  I'm not sure for how long, but it might 
make sense to deprecate for at least two subminor releases (eg if a 
feature is not deprecated until 1.2.0 it must remain in existence 
until 1.4.0).  We have a way to make this much easier now using 
macros in GNUstep-base.
The GSOnceMLog() and GSOnceFLog() macros can be used to warn about 
the use of deprecated methods/functions at runtime, but more 
importantly the GS_API_VERSION() macro should be used in headers to 
indicate (in the second argument) the release version at which 
features will cease to exist.
So, when we intend to make a new release we can quickly grep the 
headers to find out what has been deprecated and is due to be 
removed, and autogsdoc can ensure that a comment about the 
deprecation appears in the documentation of all releases prior to the 
actual removal.










reply via email to

[Prev in Thread] Current Thread [Next in Thread]