About Husky Software Version Numbers and CVS Branches
=====================================================
Husky software is developed over the internet using CVS. A large group of
programmers is simultaneously working on the code, constantly adding
features, fixing bugs, but also inadvertantly introducing new problems. In
order to provide the best level of qualtiy to our users, while at the same
time not restricting creativity of our developers, the Husky team therefore
has decided to split it's software into two branches: A development
branch, and a stable branch. This text describes the consequences of this
for users and developers.
1. Users's point of view
------------------------
1.a current branch
------------------
The development branch of Husky software may carry two or three version
numbers, like "hpt 1.3" or "hpt 1.3.17" or similar. The second digit of a
development branch version number (in the example above the "3") must always
be a odd number (not divisble by 2). Development branch version numbers are
not unique - there could be several flavours of "hpt 1.3" that behave quite
differently. Thus, the authoratitive identifier of a development branch
software is not the version number, but the cvs source code date stamp, which
is usually advertised right after the version number. Users that use current
software must always get *all* husky packages at once (i.E. with the same cvs
source code date stamp) and recompile verything from scratch. Multiple sort
of problems may arise. This is not very comfortable for the user.
1.b stable branch
-----------------
When we make a release, we fork off a "stable" branch from the main branch.
Software from the stable branch is release level software. "stable" branches
always have an even (divisible by 2) digit as the second version number. For
example, hpt "1.0" is stable, while "hpt 1.1" is not stable. Usually, the
fact that the software is from the stable branch is also advertised using a
"-stable" or "-current" prefix, like "hpt 1.0.0-stable".
After we have done a public release, we probably get some bug reports for
this. In order to provide fixes for this bugs to the users without forcing
the users to use the current development version (which also contains the
fixes, but probably also new bugs etc.), it may happen that we do another
release from the stable branch with the same basic version number. Such a
maintainance release is denoted by the third version number, e.g. "hpt
1.0.1-stable" is the first bugfix release for "hpt 1.0.0-stable".
We try hard to guarantee interoperability between the different releases
from the same stable branch. A users who has installed the first stable
release, like e.g. "fidoconfig 0.12-stable" and "hpt 1.0.0-stable", can
safely upgrade to any subsequent stable release from the same branch and be
sure that
- He does not have to change anything in his configuration files
- He does not have to recompile (or even update) the libraries he uses.
This means that he can upgrade "hpt 1.0.0-stable" to "hpt 1.0.3-stable"
but leave fidoconfig untouched, or he can upgrade only fidoconfig, but
leave hpt as is. Of course he can also upgrade both if he wants to.
- He will mostly inherit only bug fixes, but not features or other major
behaviour changes. Even if a bug fix is so complex that we cannot make
sure to integrate it without introducing side effects, it will NOT appear
in the stable branch.
Of course, interoperability is only guaranteed inside a single branch. When
you upgrade to a different branch, e.g. from "hpt 1.0.3-stable" to "hpt
1.2.0-stable", you will probably still have to update your libraries and
expect all sorts of configuration syntax and other behaviour changes.
Programmer's View
-----------------
For most developers, not much will change. Just work and commit like you
did before. However the following are general consequences that affect ALL
persons that are able to commit to CVS, no matter if a release is currently
pending or not:
- Check in modifications one by one. Don't group multiple logically
independent modifications into a single checkins. In particular, never
check in bug fixes together with new features. This ensures that fixes
can be migrated easily between the branches.
- DO provide meaningful CVS log messages. PLEASE!
The following describes the release procedure:
When a maintainer of a project wants to do a release, he creates a "stable"
branch for this version. This works like this:
- Checkout a fresh copy of the software.
- In the working directory, run "cvs tag -b TAG", where TAG is composed of
program name and ONLY THE FIRST TWO DIGITS OF THE version number with
underscores and "-stable", like e.g. "hpt-1_0-stable".
Don't forget the "-b" argument!!!
- Remove the entire working directory.
- Go to a subdirectory where you want to store working copies of the stable
branch (use a different one than you normal working root in order not to
get confused) and run "cvs co -r TAG MODULENAME"
- Change the VERSION file in your project directory to include the
"-stable" suffix in the verison number. Check in that change.
- Post a message to FIDOSOFT.HUSKY saying that you have created the branch,
tell the others the TAG you chose, and say that you plan to do a release.
After you created the branch, all checkins that you did in the copy that
you checked out using "cvs co -r TAG MODULENAME" will ONLY go to the stable
branches, while checkins that you do in directories that have been checked
out without the "-r" directory (i.E. those of most other developers) will
ONLY go to the development branch. So be careful that you do checkins from
the right directory.
Current branch do not have named CVS tag, use HEAD pseudo tag instead.
Here are some rules for creating a -stable branch
- Do it at a point when the software is already rather stable.
- If your software uses libraries like smapi or fidoconf, you must find a
stable version of those libraries to link your program against (creating a
stable branch that needs to be linked against unstable libraries is not
acceptable). If the last stable version of the librarie is not enough to
build your program, as the maintainers of the libraries to create a new
stable branch for them.
ALL HUSKY DEVELOPERS should be aware of the fact when a stable branch
exists. EVERY developer that does a bug fix after a stable branch existed
should decide if this bug fix must also be applied to the stable branch.
If so, he has two choices
1. inform the program maintainer about the fix and let him do the work of
checking it into the stable branch
2. commit the fix directly to the stable branch
Choice 2. is only for developers who are well accustomed to using CVS and
who are well accustomed with the inner workings of the program they are
modifying. Committing to the stable branch is not to be taken lightly -
errors that you make there are much more fatal than when you make them in
the current branch. If you feel unsure, you'd better not do it and leave
commiting to the stable branch to the project maintainer.
Now, here are some rules that you MUST ALWAYS ABIDE TO if you commit
anything to a -stable branch:
1. Never commit new features. Only commit bug fixes.
2. If a bug fix is very complicated (i.E. contains rather rewrites of parts
of the code), think about if it is really necessary. If you think that
users can also live without this fix, then don't commit it.
3. IN A LIBRARY - NEVER EVER CHANGE CALLING CONVENTIONS. Users must be
able to use any stable software with the any version of the
corresponding stable library. This means that in a stable library
branch, you MUST
- NEVER change the parameter list of non-static functions
- NEVER do a single change to structures that are passed on to the
calling programs (in particular, the fidoconfig structure). This means
that you never are able to introduce new keywords to fidoconfig once
you are in a stable branch.
- NEVER change linkage relevant flags in the makefiles (like pascal vs.
C calling style, structure packing flags, etc.)
4. Once the first release from a stable branch has been made, be even more
careful with your checkins. Once a release has been made from the
stable branch, maintainance releases could be made at any moment if
necessary. So be sure that everything you commit works from the moment
that you check it in.
5. If in doubt, ask others.
Finally, here comes the technical info on how to migrate fixes betwee the
current and the stable branch.
Here are some rules for creating a release.
- For release point please set tag like 'hpt-1_0_1-release': module hpt, major
version number '1', minor version number '0', patch level '1' (first release
in branch 1_1-stable). For second release in this branch can be used tag
hpt-1_0_2-release.
- Also please change version information printed by program and create/update
VERSION file, placed into root level of module directory. VERSION file must
contents three lines:
1: version ID (hpt 1.0.1-release)
2: CVS tag value
3: dependencies
Example:
hpt 1.2.2-stable
cvs tag: hpt-1_2-stable
required: fidoconfig 0.14-stable, smapi 2.2-stable
Suppose a developer has informed me that he did a patch to file "scan.c" in
project hpt". Suppose I store the current checkout of hpt in
"e:\home\husky\hpt", and the stable checkout of hpt in
"e:\home\husky\stable\hpt".
- First, look at the log file of scan.c:
[E:\home\husky\hpt\src] cvs log scan.c
- From the log file, find out which version number corresponds to the fix
that you want to migrate. Let's suppose it is 1.103
[ Note: the preceding two steps are superfluous if it was yourself who
wrote the fix. In this case, you will already know this version number
from the output of the checkin command ]
- View the contents of the fix:
[E:\home\husky\hpt\src] cvs diff -r 1.102 -r 1.103 scan.c | less
- Make double sure that this checkin ONLY contains the fix that the perosn
mentioned, and not any other side effects. If it does contian other
things, you will have to manually redo his relevant changes in the stable
directory and commit it there. This is work. However, if the
differences between 1.102 and 1.103 only contain things that you want to
migrate, you can do it as follows. I hope you now understand why I ask
every developer to commit fixes ONE BY ONE!
- Make double sure that the changes comply to the rules for stable checkins
laid out above.
- Change into the stable checkout directory and apply the patch as follows:
[E:\home\husky\stable\hpt\src]cvs update -j 1.102 -j 1.103 scan.c
It is important that you use "-j" and NOT "-r". If you get conflicts,
resolve them.
- Update the Changelog.
- Commit your changes:
[E:\home\husky\stable\hpt]cvs ci
A final word: This short introduction does not relieve you from the
necessity to read the CVS manual. It contains a chapter called "branching
and merging", and you should have read that one before doing anything on
any Husky stable branch.
Thanks for your support!
[EOF]
