Difference between revisions of "Source Release for BES"

From OPeNDAP Documentation
(WHAT ABOUT THE VERSION NUMBERS IN THE .spec FILES?)
(Update Release Related Files)
Line 52: Line 52:
 
=== Update Release Related Files ===
 
=== Update Release Related Files ===
 
Update the text documentation files and version numbers in the configuration files:
 
Update the text documentation files and version numbers in the configuration files:
==== <font color="red">WHAT ABOUT THE VERSION NUMBERS IN THE .spec FILES?</font> ====
 
  
 
==== Update the '''ChangeLog''' file. ====
 
==== Update the '''ChangeLog''' file. ====
Line 63: Line 62:
 
==== Update the version numbers ====
 
==== Update the version numbers ====
 
;background
 
;background
: There are really 2 version numbers for each of these project items. The human version (like bes-3.17.5) and the Linux API/ABI version which is represented as <tt>CURRENT:REVISION:AGE</tt>. There are special rules for when each of the numbers in the Linux API/ABI version get incremented that are triggered by the kinds of changes that where made to the code base. The human version number is more arbitrary. So for example, we might make a major API/ABI change and have to start with a a whole Linux version like <tt>25:0:0</tt> but the human version might only change from bes-3.17.3 to bes-3.18.0
+
: There are really 2 version numbers for each of these project items. The human version (like bes-3.17.5) and the Libtool API/ABI version which is represented as <tt>CURRENT:REVISION:AGE</tt>. There are special rules for when each of the numbers in the Libtool API/ABI version get incremented that are triggered by the kinds of changes that where made to the code base. The human version number is more arbitrary. So for example, we might make a major API/ABI change and have to change to a new Libtool version like <tt>25:0:0</tt> but the human version might only change from bes-3.17.3 to bes-3.18.0
  
 
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.''
 
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.''
 +
 +
===== Updating the Human Version Number =====
 +
 +
===== <font color="red">WHAT ABOUT THE VERSION NUMBERS IN THE .spec FILES?</font> =====
 +
 +
===== Updating the Libtool Version Number =====
 +
 +
Determine the new Libtool version (assuming you don't already know the extent of the changes that have been made)
 +
: For C++, build a file of the methods and their arguments using:
 +
:: <tt>nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs</tt>
 +
: and compare that using <tt>diff</tt> on the previous release's library.
 +
 +
And assess the changes you find based on these rules for the values of <tt>CURRENT</TT>,<tt>REVISION</TT>ad , <tt>AGE</TT>
 
===== libtool versioning rules=====
 
===== libtool versioning rules=====
 
What the ''CURRENT[:REVISION[:AGE]]'' string passed to ''libtool means'' (''Note these are set using variables in the configure.ac script.'')
 
What the ''CURRENT[:REVISION[:AGE]]'' string passed to ''libtool means'' (''Note these are set using variables in the configure.ac script.'')
Line 71: Line 83:
 
* Interfaces added, none removed (good): ==> Increment CURRENT, increment AGE, set REVISION to 0.
 
* 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.
 
* 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:
 
:: <tt>nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs</tt>
 
: and compare that using <tt>diff</tt> 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).
+
Make sure that '''README(.md)''', '''INSTALL''' and '''NEWS''' are updated (setting ''check-news'' in ''Makefile.am'' ''AUTOMAKE_OPTIONS'' will enforce this).
  
 
==== Commit & Push these changes. ====
 
==== Commit & Push these changes. ====

Revision as of 23:16, 23 May 2017

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

Use the developers at opendap.org list to send out notices to all the developers about pending releases.

1.1 Planned release

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 time to get their code and documentation changes into github and onto the master branch in time for the release.

Run Coverity!

1.2 Emergency releases

If this is an 'emergency' release, then send out a notice to developers as soon as the decision to release is made, since 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 of a particular component, 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.

Maybe run Coverity - depends on the scope of the changes.

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.
Create the release branch.
  • git checkout -b hyrax_release_0.0.0
  • git push --set-upstream origin hyrax_release_0.0.0
For the bes, also make the branch for each submodule:
  • git submodule foreach 'git checkout -b hyrax_release_0.0.0'

2.1 Verify the code base

  1. Make sure that the source code you're using is up-to-date. (git pull)
  2. Have all tickets for the release milestone been resolved?
  3. Does the code pass it's tests?
    Note
    For the BES (or any software that requires parameters passed to configure) use DISTCHECK_CONFIGURE_FLAGS=... when you run make For running 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).
    • libdap4
    make check -j9
    make distcheck -j9
    • bes
    make check -j9
    make distcheck -j9 DISTCHECK_CONFIGURE_FLAGS=--with-dependencies=$prefix/deps
    How did that go, with the distcheck target there? Look here for help

2.2 Check the make rpm target

Running the make rpm target is useful because it will find problems that can slow the process once the final edits are done and the RPMs are being built.

  1. Make sure to install the libdap rpms before you build the bes rpms and uninstall them afterwards.:
    sudo yum install ~/rpmbuild/RPMS/x86_64/libdap-*
  2. 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 the lib dir, 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
  3. Build the BES rpm using those snazzy static libraries, use
    make all-static-rpm -j9
  4. When finished, uninstall the libdap rpms:
    sudo yum uninstall ~/rpmbuild/RPMS/x86_64/libdap-*

2.3 Checkpoint

Up until now you have only but verified the software's readiness for release. Beginning with the follow section you will be making the edits and changes required to update the version numbers and build the actual release files. Do not proceed unless you have passed all of the previous process checks. Thanks.

2.4 Update Release Related Files

Update the text documentation files and version numbers in the configuration files:

2.4.1 Update the ChangeLog file.

Use the script gitlog-to-changelog (which can be found with Google) to update the ChangeLog file by running it using the --since="<date>" option with a date one day later in time than the newest entry in the current ChangeLog. Save the result to a temp file and combine the two files:

cat tmp ChangeLog > ChangeLog.tmp; mv ChangeLog.tmp ChangeLog

If you're making the first ChangeLog entries, then you'll need to create the ChangeLog file first.
Tip: When you're making the commit log entries, use line breaks so ChangeLog will be readable. That is, use lines < 80 characters long.

2.4.2 Update the NEWS file

To update 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.

2.4.3 Update the version numbers

background
There are really 2 version numbers for each of these project items. The human version (like bes-3.17.5) and the Libtool API/ABI version which is represented as CURRENT:REVISION:AGE. There are special rules for when each of the numbers in the Libtool API/ABI version get incremented that are triggered by the kinds of changes that where made to the code base. The human version number is more arbitrary. So for example, we might make a major API/ABI change and have to change to a new Libtool version like 25:0:0 but the human version might only change from bes-3.17.3 to bes-3.18.0

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.

2.4.3.1 Updating the Human Version Number
2.4.3.2 WHAT ABOUT THE VERSION NUMBERS IN THE .spec FILES?
2.4.3.3 Updating the Libtool Version Number

Determine the new Libtool version (assuming you don't already know the extent of the changes that have been made)

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.

And assess the changes you find based on these rules for the values of CURRENT,REVISIONad , AGE

2.4.3.4 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.

Make sure that README(.md), INSTALL and NEWS are updated (setting check-news in Makefile.am AUTOMAKE_OPTIONS will enforce this).

2.4.4 Commit & Push these changes.

2.5 Build And Upload Distribution Files

  1. Make the tar file
  2. For the BES, see below
  3. 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). -->
  4. Update the web pages: A complex and (at this time - 2/21/06) changing process.

2.6 Tag The Release

  1. git tag -a version-<numbers> -m "Version <number>"
  2. git push origin version-<numbers>

If this is part of Hyrax, also tag this point in the master branch with the Hyrax release number:

  1. git tag -a hyrax-<numbers> -m "Hyrax <number>"
  2. 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.
  3. 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

3 For the BES

This may change if the BES project is restructured.

Do the release items above for the source release and then, for the modules, do the following:

  • git submodule foreach 'git status'
  • cd modules and ./version_update_modules.sh -v `cat all_modules.txt`
  • git submodule foreach 'git status'
  • git submodule foreach 'git commit -a -m "updated for Hyrax 1.13.3"'
  • git submodule foreach 'git push'

These steps update the modules (sub-projects) and get the new version numbers up into GitHub.

Then git commit -a and git push in the bes dir to make sure that the new commit hashes get pushed.