tags:

views:

185

answers:

6

We have a C++ project, which has hundreds of SVN revisions every month. Sometimes we need to increment a minor digit in a version number, changing it from, say, 1.6 to 1.7. We do it once per month approximately. What is a correct approach to do it? We want to save/maintain information about changes made in every new version, and we want to have some sort of release notes. Please, give us some suggestions or links. Thanks!

ps. Sorry if the question is too vague.

pps. I see that I need to clarify the question a bit. I'm not interested about how should I name versions. I'm interested how technically I should maintain version numbers in C++ code.

+1  A: 

Semantic Versioning is an excellent set of guidelines for managing major/minor revisions. An advantage of using it is you can simply point people to http://semver.org to give them a complete understand your versioning system.

Matt Curtis
Thanks, but this is not exactly what I'm interested it. I just altered my question a bit, to explain my problem better.
Vincenzo
@FaZend.com: ok I've added a new answer to suggest a few ways to manage versions in your code, but I'm keeping this one here cos someone obviously found it useful and upvoted it :)
Matt Curtis
+4  A: 

I use this system for all of the software that I write:

1.2.3.4
  1. The major version number. Only increment on a "major" release that changes numerous product features.
  2. The minor version number. Increment on regular (quarterly, monthly) releases. This number is not limited to 9; feel free to go as high as you need. Don't increment this for minor fixes or updates. When the major version number is changed, this number is set to zero.
  3. The update number. Increment this number whenever you put out a series of updates. An update in my book is considered a release that contains a series of bug fixes, performance improvements, or security enhancements. There must be multiple changes for this to be incremented. This can also be greater than 9. When the minor version number is changed, this is reset to zero.
  4. The minor update number. Increment this with minor, individual changes. For instance, if you fix a specific bug and roll the patch into your last release, this would increase. This number should be reset to zero when the update number changes.

Lastly, I use the following suffixes to denote prerelease builds:

  • b: Beta
  • a: Alpha
  • rc: Release Candidate

Suffixes can be followed by a number to indicate which revision of the prerelease build the package is. For instance:

1.2.3.4b2

would be considered the second beta.

Also, when writing versions, trailing zeros can be eliminated. i.e.: 1.0.0.0 could be written as 1.0.

Hopefully this is somewhat useful. I've found that it helps keep things organized and maintains some semblance of order in my archives.

mattbasta
Thanks, but this is not exactly what I'm interested it. I just altered my question a bit, to explain my problem better.
Vincenzo
+2  A: 

For the 'release note' tracking, I suggest using some external tool to track tasks. You can assign functionalities and in many cases associate issue numbers with specific subversion commits. I have used ClearQuest and Jira for this in the past but there are opensource/free tools out there you can try.

If you decide to follow this path, make sure that each commit is tagged with the issue number, and that all issues are tagged with specific software version numbers ('resolve in'). Open an issue for each found bug. For each new release make a branch, merge the commits that are tagged with issues to be resolved in that release, and test --sometimes you can have conflicts with changes that are not meant for this release but rather a later one--. After the branch has been merged, build and tested, make a release tag from it.

Generating the release documentation is then quite simple: all the information is present in your issue tracker associated to the current release number.

I have also seen in the past the work performed the other way around: open a branch for development, perform separate changes in the branches and merge them back to the trunk, with each merge containing a descriptive text of the whole change --new functionality or bug being fixed. Create release tags from the trunk directly when needed. Getting the changes from two releases is just reading the logs from the changes to trunk from the one release to the next.

Both solutions share the same type of problems: merging is trivial in theory, but not so in practice. In the first case, when pulling code from trunk to the release branch you will have to handle merge problems when intermediate commits are not to be pulled. When developing in branches and merging back to trunk, before each merge to trunk you will have to merge first trunk changes into your branch. Build, test and then merge back to trunk.

Most subversion books will recommend the second path, but in some circumstances the first one (which is the one I am currently using makes sense). In our case we have a whole set of automated tests that run for over 20 hours, having all code written directly to the trunk means that you only need the automated tests to run there. If we were branching for each change, either we would leave the branches untested until we merged back --bad idea-- or else we would have to throw a lot more hardware in for testing and slow down development quite a bit.

David Rodríguez - dribeas
David, out of curiosity, how many lines of code you're testing for 20 hours?
Vincenzo
About 3M lines of C++, C and Java. The problem is not really the code, but the complexity of the system, some of the tests need to run for some time to gather statistics, or to trigger alerts under various circumstances.
David Rodríguez - dribeas
From all the answers so far, to me this one seems to answer the question best. `+1` from me.
sbi
A: 

You could

  • Manually maintain a version.cc file
  • Use GNU Autotools and put your version number in AC_INIT() in configure.in, then use the PACKAGE_VERSION that the configure script defines in config.h for you
  • Use tags to mark points in your repository where you bump the version number - Subversion does this with svn cp - check out more about that here
Matt Curtis
Thanks, this is what I'm looking for. The options you listed are not mutually exclusive. We're using SVN tags already, but we don't have the `version.cc` file you mentioned. In other words, we don't know what *version 1.6* means when we're working with 2.5. We're loosing the semantic of tags/versions :( This `version.cc` has to have some format?
Vincenzo
@FaZend.com: Glad this helps. In my experience `version.cc` is whatever you want, a simple string is enough. A const char* is a good start, then you can easily find it using tools like GNU binutils `strings` on your binary. You could certainly combine these options, e.g. `#include "config.h" / const char* g_version = PACKAGE_VERSION;`, or you could just have your literal version string there, e.g. your version.cc could be simply `const char* g_version = "Version 1.0.0";`. Given this is what you're looking for, please consider upvoting and accepting :) cheers, Matt
Matt Curtis
A: 

I find that including the SVN revision number as part of the version number is very useful as if a customer reports an issue with a specific build you can easily check out the related code. You can write scripts that can query for the SVN revision easily enough (I have done scripts using JScript for example), writing a special version.h header automatically. The major/minor numbers are maintained by hand but the remaining two numbers (in my case the SVN revision and a special build number representing the date of the build) are created automatically. I then use an MS Visual Studio pre-build step to execute the script ensuring it is up-to-date for every build. The header I auto-create ends up looking something like this:

#ifndef VERSION_H
#define VERSION_H

namespace Version
{
  const int MAJOR = 1;
  const int MINOR = 2;
  const int REVISION = 1234;
  const int BUILD = 10123;

  inline const char* toString()
  {
    return "1.2.1234.10123";
  }

  ...
}

#endif

To get the SVN revision from the command-line simply run svnversion from the command-line.

Rob
Rob, the approach looks very good, but still the same question - How do you know in 6 months after version 1.5.6 has been introduced what was it about? Where do you store this *semantic* information?
Vincenzo
We update a README file with every release containing a list of changes for that version.
Rob
Instead of writing a script, why don't you use the `$REVISION$` special tag so Subversion replaces the revision number itself and automatically ? Much less error prone imho.
ereOn
Because the script also generates a magic build number based on the current date.
Rob
A: 

I know WebKit patches are required to include a change to a ReleaseNotes.txt file. This might be a way to keep track of individual changes.

They have many (WebKit-oriented) scripts to help them with such tasks. They're written in perl and may have some useful bits for you.

http://trac.webkit.org/browser/trunk/WebKitTools/Scripts

Check especially - resolveChangelogs - svn-createpatch and most important: prepare-changelogs

I have not looked at the scripts, but they seem to do what you need for WebKit.

rubenvb