Source Release for BES
Note that the old pages with the tables of version numbers are gone. Use the web pages themselves as documentation of what has or has not been built. For the current release, include grayed-out links to binaries we do plan to make but keep the grayed-out links in place for the current version only!
1 When we decide to release software
If this is a planned release, send out a notice at least two weeks in advance to anyone who likely has made changes to the software. More lead time is, of course, better. This will allow developers to get their code into github and onto the master branch in time for the release.
If this is an 'emergency' release, then send out a notice as soon as the decision to release is made. this will give a chance for other developers to lets us know if there are new changes in the master branch that are ready for release. if we don't get an email from those developers, then we should assume that the code might not be 100% ready for release and we should use the version tagged with/for the last release if possible.
2 The release Process
- Tip: If, while working on the release, you find you need to make changes to the code and you know the CI build will fail, do so on a release branch that you can merge and discard later. If you don't need to do this, skip it. Also, note that the umpteen handlers really make this a hassle, so feel free to skip this step or do it only for the BES itself, etc.
- git checkout -b hyrax_release_.. then git push --set-upstream origin hyrax_release_..
- For the bes, also make the branch for each submodule: git submodule foreach 'git checkout -b hyrax_release_..'
- Make sure that the source code you're using is up-to-date and that the software passes its tests and no outstanding tickets remain for the release milestone. Make sure make check -j9 and make distcheck -j9 work. Note that for the BES, or any software that requires parameters passed to configure, use DISTCHECK_CONFIGURE_FLAGS=... when you run make. A typical distcheck for the BES is make distcheck -j9 DISTCHECK_CONFIGURE_FLAGS=--with-dependencies=$prefix/deps and yes, it's a pain to type... For tests, using TESTSUITEFLAGS=-j9 will speed up the autconf/autotest tests if the version of autoconf supports parallel testing (but not on CentOS 6 because it's not supported by the stock version of autoconf on that OS).
- Checking make rpm is useful for a beta release because it will find problems that can slow the process once the final edits are done and the RPMs are being built. Make sure to install the libdap rpms (e.g., sudo yum install ~/rpmbuild/RPMS/x86_64/libdap-*) before you build the bes ones and uninstall them afterwards. Make sure that the bes dependencies have been built using the static option so that the BES rpm will have modules that are statically linked to their dependencies. To check this, look at the libraries in $prefix/deps/lib. There should be no *.so files in 'lib', only *.a, *.la, and some other directories. To build a new set of dependencies that provide only static libraries, use make for-static-rpm -j9 CONFIGURE_FLAGS=--disable-shared. To build the BES rpm using those snazzy static libraries, use make all-static-rpm -j9.
- Update the text documentation files and version numbers in the configuration files:
- Update the ChangeLog file using the script gitlog-to-changelog which can be found with Google. Run it using the --since="<date>" option and use a date one day later then the newest entry in the current ChangeLog. Save the result to a temp file and combine the two files (cat tmp ChangeLog > ChageLog.tmp, ...). If you're making the first ChangeLog entries, then you'll need to create the ChangeLog file first. Here's a key tip: When you're making the commit log entries, use line breaks so ChangeLog will be readable. That is, use lines < 80 characters long.
- Then to write the NEWS file, just read over the new ChangeLog entries and summarize. In the old days of CVS, the logs automatically included the names of the changed files, but subversion and git don't do that.
- Make sure that the version number is set in the configure.ac and *.spec files! For the BES handlers, the version information is also int he Makefile.am (look for the M_VER= line). When the version number changes, reset the RPM release number to '1' in the *.spec files ("Release: 1"). For several releases of the same version, increment the release number (the number after the dash in the RPM file name; we don't have release numbers for the tar files). I generally update the ChangeLog before updating the version numbers or NEWS, et c., files because the ChangeLog gives me a bird's eye view of what happened since the last release.
- libtool versioning rules: What the CURRENT[:REVISION[:AGE]] string passed to libtool means: (Note these are set using variables in the configure.ac script.)
- No interfaces changed, only implementations (good): ==> Increment REVISION.
- Interfaces added, none removed (good): ==> Increment CURRENT, increment AGE, set REVISION to 0.
- Interfaces removed or changed (BAD, breaks upward compatibility): ==> Increment CURRENT, set AGE and REVISION to 0.
- So how do you know? For C++, build a file of the methods and their arguments using nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs and compare that using diff on the previous release's library.
- Make sure that README, INSTALL and NEWS are updated (setting check-news in Makefile.am AUTOMAKE_OPTIONS will enforce this).
- Commit & Push these changes.
- Make the tar file - make dist
- Sign the tar file. See the help item on the main trac wiki page if you need instructions.
- Move the file to the web site for distribution.
- Make the RPM
- Sign the RPM
- Move to a directory on the web site and use script to move the RPM around (later, once all the RPMs are uploaded). -->
- Update the web pages: A complex and (at this time - 2/21/06) changing process.
- Tag the release:
- git tag -a version-<numbers> -m "Version <number>"
- git push origin version-<numbers>
- If this is part of Hyrax, also tag this point in the master branch with the Hyrax release number:
- git tag -a hyrax-<numbers> -m "Hyrax <number>"
- git push origin hyrax-<numbers>
- NB: Instead of tagging all of the modules, use the saved commit hashes that git tracks for submodules. This cuts down on the bookkeeping for releases and removes one source of error; recording the wrong version for one of the 17 or so modules. thus, there is no need to tag the code in the modules.
- Mark the release on Github:
- Goto the 'releases' page and click the 'Tags' tab. There:
- Enter a title for the release
- Copy the most recent text from the NEWS file into the describe field
- Click Update this release or Save draft
- Goto the 'releases' page and click the 'Tags' tab. There: