Powerful Open Source LDAP

From Port389

Contents

Versioning

Some background on version numbering is available here - http://en.wikipedia.org/wiki/Software_versioning.

Naming

A full version name will be PACKAGENAME - VERSIONNUMBER e.g. 389-ds-base-1.2.5. The PACKAGENAME part will be the name typically given to the binary package. This name will also be used in the source. For packages that use autoconf for building, this will be the PACKAGE_TARNAME setting. The goal is that the full version name and number used in the source tarball name is the same as the SCM tag name of the tag used to produce that source tarball, and is the same as the name of the binary package. For autoconf packages, this also means the same source tarball name as produced by a make dist. 

NAME=<name of package>
VERSION=<version number>
SRCNAME=$NAME-$VERSION
TAG=$SRCNAME

git tag $TAG
git archive --prefix=$TAG/ $TAG | bzip2 > $SRCNAME.tar.bz2
make dist -> $SRCNAME.tar.bz2
rpmbuild $NAME.spec -> $NAME-$VERSION.<dist>.<platform>.rpm # for RPM platforms

There are a couple of important exceptions to this:

  • The DS base and admin packages use an autoconf package name of dirsrv and dirsrv-admin - this is the name used to name files and directory paths (e.g. /etc/dirsrv). This is not the same as the name of the source tarballs and binary packages.
  • For RPMs, the RPM version number cannot be the same as the source version number for pre-release builds only, due to the way RPM calculates package dependencies and upgrades - see below

Source Version

The source version is the version number/string assigned to the source code and the SCM tag. It is comprised of several parts. In general, the version numbers look like this: 

MAJOR.MINOR.MAINTENANCE.PRE-RELEASE

or 

MAJOR.MINOR.MAINTENANCE.PATCH

examples: 

1.2.3 # an official release
1.2.3.a1 # alpha 1 pre-release of 1.2.3
1.2.3.a4.git283abc3 # alpha 4 pre-release of 1.2.3 from a git commit with short commit hash 283abc3
1.2.3.rc1 # release candidate 1 of 1.2.3
1.2.3.1 # patch release 1 for 1.2.3

The PRE-RELEASE part (explained below) is optional, and indicates software that has not been officially released, in alpha, in testing, or a release candidate. The fields in the version number are explained below:

  • MAJOR - an integer - the major version - this only changes for very large or incompatible changes in the code
  • MINOR - an integer - the minor version - this changes when substantial changes are in the code
  • MAINTENANCE - an integer - this can change when there are small but non-trivial changes to the code (new functionality, bug fixes, errata)
  • PRE-RELEASE - (optional) - a string
    • a - indicates an alpha release - should be followed by an integer indicating which alpha release this is e.g. a1
    • rc - indicates a release candidate - should be followed by an integer indicating which release candidate this is e.g. rc1
    • The first alpha release is a1, then a2, etc. The first rc release is rc1, then rc2, etc. - just bump the number by 1 each time
    • additional text may appear after the aN or rcN - for example, if you want to mark the build with a git commit hash:
      • 1.2.3.a3.git23ab3512
      • Note that if the source is tagged often, the VERSION.PRE-RELEASE will already correspond exactly to an SCM tag, so using a git commit hash like this is probably not necessary
  • PATCH - an integer - indicates a patch to a MAJOR.MINOR.MAINTENANCE release

Tag Version

The version number part of a tag name will be exactly the same as the Source Version described above. This will allow us to go from a source tarball name to a git tag (and therefore a complete git tree). In git, tags are cheap and don't have the restrictions that plague CVS tagging, so we should use tags as much as possible.

Package Version

In general, we follow the Fedora Packaging Guidelines - https://fedoraproject.org/wiki/Packaging:NamingGuidelines - However, this means that the source/tag will not be identical to the package name-version-release. This will involve some complication in the RPM spec file for pre-release builds and snapshot builds. Fedora uses VERSION - RELEASE (e.g. 1.2.3-1) for the full version numbering and package naming. The VERSION is the dotted triplet of integers corresponding to the MAJOR.MINOR.MAINTENANCE. For official, blessed releases, the RELEASE is just a single integer that increments each time the spec is changed. For pre-releases, the RELEASE will begin with a 0., followed by the regular monotonically increasing release number, followed by the PRE-RELEASE part of the source/tag version. Here are some examples.

Source Spec V-R Comment
1.2.3.a1 1.2.3-0.1.a1 first alpha pre-release of 1.2.3
1.2.3.a2 1.2.3-0.2.a2 second alpha pre-release of 1.2.3
1.2.3.a3.git83fad321 1.2.3-0.3.a3.git83fad321 third alpha pre-release with git commit hash appended
1.2.3.rc1 1.2.3-0.4.rc1 first release candidate pre-release
1.2.3.rc2 1.2.3-0.5.rc2 second release candidate pre-release
1.2.3.0 1.2.3.0-1 first official 1.2.3 release
1.2.3.0 1.2.3.0-2 1.2.3 rebuild - release number is bumped (e.g. spec file changed but not source)
1.2.3.1 1.2.3.1-1 1.2.3.1 patch release - release number is reset to 1 (e.g. spec file changed but not source)

Notice that for pre-releases, the release field changes each time, and does not necessarily correspond to the number associated with the a or the rc. For example, a1 -> 0.1, a2 -> 0.2, a3 -> 0.3, but rc1 -> 0.4. The RELEASE field behaves for pre-releases exactly the same way it behaves for regular releases, except that for pre-releases, it begins with a 0..

This means, however, that the spec file cannot use the Version: field for both the package version and the source version. The spec file will need some special handling to account for this and for pre-releases. 

# since this is a pre-release, define the prerel field - comment out for official release
%define prerel .a4
# also need the relprefix field for a pre-release
%ifdef prerel
%define relprefix 0.
%endif
...
Name: 389-ds-base
Version: 1.2.3 # note - same as source version
# if this is an official release, prerel will be commented out and both prerel
# and relprefix will therefore not be defined, so %{?relprefix} and %{?prerel}
# will expand to nothing giving us a V-R of 1.2.3-1
# if prerel and relprefix are defined, we will have a V-R like 1.2.3-0.4.rc1
# if version or prerel changes, reset to %{?relprefix}1%{?prerel}%{?dist}
Release: %{?relprefix}1%{prerel}%{?dist}
...
Source0: http://port389.org/source/%{srcname}-%{version}%{?prerel}.tar.bz2
...
%prep
%setup -q -n %{srcname}-%{version}%{prerel}

Doing the numbering this way preserves RPMs ability to do upgrades, since X.Y.Z-1 > X.Y.Z-0.1.something

Changing the Version

Large packages that will have many version changes, such as the core directory server and admin server, will use a file called VERSION.sh that holds the version and other fields used to name the package. This will allow us to change the version without having to edit configure.ac, run autogen.sh, etc. Packages that don't change very often will just use the version field of AC_INIT in configure.ac, and will have to perform autogen.sh. This shouldn't be a big deal for packages that do not change very often.

Release Procedure

Official Release - Version and Tag

0. Use the git work flow specified at GIT_Rules to make sure you apply the version changes correctly and without merging.

1. Change the version number to remove any pre-release strings. For example, if the version were specified as 1.2.3.rc2 in VERSION.sh: 

VERSION.sh:
...
VERSION_PREREL=rc2

just comment out the VERSION_PREREL 

#VERSION_PREREL=rc2

If this is a project that just uses AC_INIT to specify the version and not VERSION.sh, edit configure.ac, change the version to remove the pre-release part, and run autogen.sh.

2. commit the changes to the SCM 

git add VERSION.sh # or configure.ac, configure, Makefile.in, any other file changed by autogen.sh
# you could just use git commit -a -m instead of first doing git add, but you must make sure
# there are no other files which would be picked up by -a - git status
git commit -m "bump version to 1.2.3 for official release"

3. tag the release 

# git rebase, checkout master, and merge if necessary - see GIT_Rules
# apply the tag on the main branch (e.g. master) you are working on, not on a private side branch
git tag 389-ds-base-1.2.3
# also apply the RELEASE tag - use -f to move the existing tag
git tag -f RELEASE

Note that with git a tag is just an "alias" for a commit - you can easily view the commit associated with the tag, including the timestamp, so there is no need to create timestamped tags. The RELEASE tag allows someone to get the latest official release.

4. push the version change commit and the tag to the upstream repo 

git push fedora master
git push --tags fedora master # tags are not pushed by default

make sure you have no local tags that you do not want to push

5. check the upstream repo to verify your commit and tag - you can just web browse to http://git.fedorahosted.org/git/?p=389/ds.git

The active tree should always be in the pre-release state - anyone pulling the tree using the tag HEAD or git fetch/pull should always see a pre-release tree. The only way to get an officially released source code tree is to pull from an official release tag.

So, after making an official release, you will have to put the tree back in the pre-release state for the next release - see below.

Pre-Release - Version and Tag

As noted above, the tree should always be in the pre-release state, starting with a1. To move to the next pre-release:

1. Change the pre-release field

  • if moving from an official release to a pre-release, change the MAINT number to the next one, and change the pre-release number to a1
  • if moving to the next alpha or release candidate, just change the number after the a e.g. a2 -> a3
  • if moving to a release candidate, change the aN to rc1 e.g. a4 -> rc1 
VERSION.sh:
VERSION_PREREL=a1

change to 

VERSION_PREREL=a2

If this is a project that just uses AC_INIT to specify the version and not VERSION.sh, edit configure.ac, change the version (e.g. from 1.2.6.a1 to 1.2.6.a2), and run autogen.sh.

2. commit the changes to the SCM 

git add VERSION.sh # or configure.ac, configure, Makefile.in, any other file changed by autogen.sh
# you could just use git commit -a -m instead of first doing git add, but you must make sure
# there are no other files which would be picked up by -a - git status
git commit -m "bump version to 1.2.6.a2 for alpha 2"

3. tag the release 

# git rebase, checkout master, and merge if necessary - see GIT_Rules
# apply the tag on the main branch (e.g. master) you are working on, not on a private side branch
git tag 389-ds-base-1.2.6.a2

4. push the version change commit and the tag to the upstream repo 

git push fedora master
git push --tags fedora master # tags are not pushed by default

make sure you have no local tags that you do not want to push

5. check the upstream repo to verify your commit and tag - you can just web browse to http://git.fedorahosted.org/git/?p=389/ds.git

Create the source tarball

Start from a TAG (PACKAGE-VERSION) which was created using the above tagging procedure.

You can use git: 

git pull fedora master # get the latest changes and tags
git archive --prefix=TAG/ TAG | bzip2 > /path/to/TAG.tar.bz2

or you can use wget if the repo supports gitweb snapshots: 

wget http://git.fedorahosted.org/git/?p=389/ds.git;a=snapshot;h=TAG;sf=tgz
# gitweb snapshot does not support bzip2, so we have to repackage:
tar xfz TAG.tar.gz
tar cfj TAG.tar.bz2 TAG
rm -rf TAG TAG.tar.gz
Retrieved from "http://directory.fedoraproject.org/wiki/Release_Procedure"
Account