Read Me

This is a cookbook showing the steps required to create a libLASi release at
SourceForge.

INDEX
(0)  Set some useful version-related environment variables 
(1)  Create and test a preliminary tarball from trunk
(2)  Finish release-related trunk changes so they will be in the release
(3)  Create and test the release tarball from trunk
(4)  Update ChangeLog and README.Release_Manager_Cookbook
(5)  Tag the release
(6)  Create and test the release tarball from the tagged version
(7)  Generate a file release at Sourceforge
(8)  Commit the tagged version
(9)  Publicity for the release announcement
(10) Post release tweaking of this file (README.Release_Manager_Cookbook)

(A1) GNU Privacy Guard (gpg).
(A2) Setting the correct date and time on your computer.
End of INDEX

(0)  Set some useful version-related environment variables

Setting these environment variables make the remaining steps in the
release process less prone to errors and also easier to document (as in this file)
in a version-invariant way.

export OLD_VERSION=1.1.3
export VERSION=1.1.4
export MINIMUM_CMAKE_VERSION=3.13.4
export MAXIMUM_CMAKE_VERSION=3.16.2

(1)  Create and test a preliminary tarball from trunk

     This (extensive sets of tests) is just to make sure that the trunk version
     is in good shape before you do the following final stages of the
     release process.     

     Do the tests in (3) below using the old lasi version (since that version
     has not been updated yet).

export LASI_VERSION=$OLD_VERSION

To save a factor of two in time just execute 6 tests (with the minimum cmake version choice)
rather than all 12 versions of the test since this is just a preliminary test to give
us some confidence that all is well at this stage.

To save a very large factor in time also drop the PLplot component of this preliminary test
export -n PLPLOT_CMAKE_PATH
export -n PLPLOT_SOURCE_PREFIX

(2)  Finish release-related trunk changes so they will be in the release

*    set environment variable for version to make directions below
     more generic.

export LASI_VERSION=$VERSION
# Should refer to the first revision in this release cycle, i.e., one revision
# after the last revision of the previous release cycle.
export FIRST_REVISION_IN_CYCLE=r223

*    Prepare a preliminary version of the ChangeLog file to see what
     has been accomplished since the last release.

# This makes the BASE used below correct.
svn update

svn log --revision ${FIRST_REVISION_IN_CYCLE}:BASE --verbose  >| ChangeLog.release_preliminary

     Note the "_preliminary" suffix to distinguish this from the final
     result below which will contain (if all goes well in the steps
     below) a record of all but the last commit (of the ChangeLog
     itself) for this release.

     Note the order of the --revision components puts this preliminary
     version in chronological order.  But it is traditional for the
     final version to have the result in reverse chronological order
     (see below).

*    Update and commit README and cmake/module/lasi_version.cmake to
     reflect the current version. Also, follow the instructions in
     that latter file for updating the SOVERSION, the minor number and
     the patch number.

*    Update and commit the release notes (stored in the README.release
     file) containing a short overview of the most important changes
     noted in the ChangeLog.release_preliminary file since the last
     release.

*    Once completely satisfied with README.release insert it at the
     start of README.cumulated release to keep a historical record in
     reverse chronological order of the notes for all releases in that
     file.  From now on, any further tweaks to README.release should
     be mirrored in README.cumulated release which is why this
     insertion step should be delayed until the release manager is
     completely satisfied with README.release.

*    Check that all local changes (other than this file,
     README.Release_Manager_Cookbook, and ChangeLog) are in the
     repository so they will be reflected in the ChangeLog, tagged
     version of the release, and release tarball.

svn status

(3)  Create and test the release tarball from trunk

*    Do the usual cmake and make in the build tree to build the user
     and developer configurations of the Doxygen documentation in the
     source tree.  For example,

pushd /home/software/lasi_svn/HEAD/build_dir
# Check LASI_VERSION is set properly
echo $LASI_VERSION
# N.B. using the minimum version of cmake allowed by our build system.
time (rm -rf /home/software/lasi_svn/HEAD/build_dir/* ~/lasi_svn/install; env PATH="/home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin:$PATH" cmake -DCMAKE_INSTALL_PREFIX=/home/software/lasi_svn/install -DBUILD_SHARED_LIBS=ON ../lasi_2019 >& cmake.out)
# BUILD to assure documentation is built with results copied to source tree.
make -j18 all >& all.out

# Build a preliminary version of the release tarball

make package_source

# Check that generated tarball by checking its table of contents as follows:

tar ztvf libLASi-$LASI_VERSION.tar.gz |sed "s?  *? ?g" |cut --delimiter=" " --fields="6-" |less

# Test that tarball

# Setup the test by creating the following environment variables:

export LASI_VERSION
export PARALLEL_OPTION=-j18

# Set PLplot-related environment variables.
# N.B. if either of PLPLOT_CMAKE_PATH or PLPLOT_SOURCE_PREFIX are not set below
# the script ignores the important PLplot component of
# libLASI testing.

# Use minimum allowed version of CMake for PLplot during special comprehensive test
# of PLplot that externally tests libLASi.
export PLPLOT_CMAKE_PATH=/home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin

# Choose this prefix to assure that the PLplot source tree has
# a blank in its pathname.  This combined with choosing a comprehensive test prefix
# inside the script with a blank in the pathname assures that the case where there
# are blanks in the source, build, and install tree prefixes is tested by this
# comprehensive test.
export PLPLOT_SOURCE_PREFIX="/home/software/plplot/HEAD/plplot blank .git"


./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=ON -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=ON -DLASI_LINK_PUBLIC=ON
./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=OFF -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=OFF -DLASI_LINK_PUBLIC=ON
./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=ON -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MINIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=ON -DLASI_LINK_PUBLIC=ON

./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=ON -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=ON -DLASI_LINK_PUBLIC=ON
./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=OFF -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=OFF -DLASI_LINK_PUBLIC=ON
./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=ON -DLASI_LINK_PUBLIC=OFF
./test_tarball.sh /home/software/cmake/install-${MAXIMUM_CMAKE_VERSION}/bin -DBUILD_SHARED_LIBS=OFF -DPREFER_EXTERNAL_STATIC=ON -DLASI_LINK_PUBLIC=ON

# If any of these 8 tests reveal that trunk changes are necessary, do
# those, retest, and iterate until perfect results are obtained.

(4)  Update ChangeLog and README.Release_Manager_Cookbook

*    Update this file (README.Release_Manager_Cookbook) as much as
     possible concerning what has been done to complete this release
     and commit that result.  However, if some subsequent deviations
     occur from the instructions in this cookbook then this file
     should also be tweaked after the release (see (10)).
svn commit README.Release_Manager_Cookbook

*    Prepare a (hopefully) final version of the ChangeLog file and commit it.
svn update
svn log --revision BASE:${FIRST_REVISION_IN_CYCLE} --verbose  >| ChangeLog.release_preliminary
mv ChangeLog.release_preliminary ChangeLog.release
svn commit ChangeLog.release

(5)  Tag the release

     Based on suggestions in the svn manual, the libLASi svn archive
     is configured as follows:

branches/
tags/
trunk/

     For the release, you will be creating (and eventually committing)
     what is essentially a branch of libLASi that is a snapshot record
     of that subproject at the time of the release. This branch will
     be located in the /tags directory and should follow the naming
     convention tags/$LASI_VERSION although prior releases used a
     different naming convention based on CVS (!) requirements.

#ONE TIME ONLY
# The easiest way to get started is to check out the _entire_ lasi svn
# repository as follows:

svn checkout https://svn.code.sf.net/p/lasi/code lasi_allura_complete

#ONE TIME ONLY completed

     If you already have this directory, you will need to make sure
     that all your commits (probably in a different local directory)
     have been done (see above) and that lasi_allura_complete is up to date
     with those commits.

cd lasi_allura_complete
svn update

# Create and commit release tag of lasi
svn copy trunk tags/$LASI_VERSION

(6)  Create and test the release tarball from the tagged version

     Do exactly the same as (3) in the usual initially empty build
     directory, but with the top of the source tree
     lasi_allura_complete/tags/$LASI_VERSION

     In the (unlikely, since this has never happened for me) event
     that problems are found in the tarball generated from the tagged
     version during the release process, corrections should be made to
     trunk/, the ChangeLog.release file recreated and committed (see
     instructions above).  Then merge the trunk version into the tags
     as follows:

cd tags/$LASI_VERSION
svn merge -r A:B /path/to/trunk

     Where A and B specify the range of revisions in trunk to be
     applied to tags/$LASI_VERSION in the merge process. These can be
     determined by commit messages.  N.B. I have never had to
     go through this procedure so the above instructions are what
     I have gleaned from other sources "just in case".

(7)  Generate a file release at Sourceforge

     A list of your GPG keys can be obtained using the command

gpg --list-keys <first name>

     where <first name> is the first name you used when creating your
     gpg key.  The result of that command for the current release
     manager (AWI) is

pub   rsa2048 2011-08-19 [SC] [expires: 2021-12-12]
      A7CED6D2D4903103FCDDFC1E418B8FC4BB159E92
uid           [ultimate] Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>
uid           [ultimate] Alan W. Irwin (libLASi key) <airwin@users.sourceforge.net>
uid           [ultimate] Alan W. Irwin (FreeEOS key) <airwin@users.sourceforge.net>
uid           [ultimate] Alan W. Irwin (PLplot key) <airwin@users.sourceforge.net>

     The A7CED6D2D4903103FCDDFC1E418B8FC4BB159E92 field above can be used for key signings,
     but more conveniently its last 8 characters can be used for that purpose, e.g.,
     BB159E92

     Also, a new curveball thrown by the Debian Testing version of gpg
     is you must identify the tty you are using with, e.g.,

export GPG_TTY=$(tty)

     (see remarks at
     <https://www.elliotblackburn.com/importing-pgp-keys-from-keybase-into-gpg/>)

     Otherwise, in my experience, gpg will refuse to sign the tag and
     you will get the error:

error: gpg failed to sign the data
error: unable to sign the tag

     But with the above trick, the following command just worked.

gpg --default-key BB159E92 --detach-sign --armor libLASi-$LASI_VERSION.tar.gz

     where BB159E92 is the last 8 characters of the full key
     identification above and is sufficient to identify the public key
     for Alan W. Irwin as taken from the above key list.  N.B. it
     appears there is no gpg model for signing with a particular user
     id.  So the signature verification below will have all UID's.

     Then verify that result:

gpg --verify libLASi-$LASI_VERSION.tar.gz.asc

     where the output of that commmand should be similar to

gpg: assuming signed data in 'libLASi-1.1.3.tar.gz'
gpg: Signature made Thu 31 Jan 2019 12:04:16 AM PST
gpg:                using RSA key A7CED6D2D4903103FCDDFC1E418B8FC4BB159E92
gpg: Good signature from "Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>" [ultimate]
gpg:                 aka "Alan W. Irwin (libLASi key) <airwin@users.sourceforge.net>" [ultimate]
gpg:                 aka "Alan W. Irwin (FreeEOS key) <airwin@users.sourceforge.net>" [ultimate]
gpg:                 aka "Alan W. Irwin (PLplot key) <airwin@users.sourceforge.net>" [ultimate]

     Copy the results to a more permanent location:

cp libLASi-$LASI_VERSION.tar.gz* /home/software/lasi_svn/HEAD/export

     Prepare a temporary file called README.release that concatenates
     README.release and ChangeLog.release.

cd ../lasi_allura_complete/tags/$LASI_VERSION

echo "

DETAILED CHANGELOG FOR THIS RELEASE

" | \
cat README.release - ChangeLog.release >| /tmp/README.release

     Upload the release to SourceForge using sftp

cd /home/software/lasi_svn/HEAD/export

sftp airwin,lasi@frs.sourceforge.net <<EOF
cd /home/frs/project/l/la/lasi/lasi
mkdir "$LASI_VERSION Source"
cd "$LASI_VERSION Source"
put libLASi-$LASI_VERSION.tar.gz.asc
put libLASi-$LASI_VERSION.tar.gz
lcd /tmp
put README.release
quit
EOF

     Demonstrate with irwin account that can download these uploaded
     results and verify them:

SITE=https://sourceforge.net/projects/lasi/files/lasi/"$LASI_VERSION Source"
wget "$SITE/libLASi-$LASI_VERSION.tar.gz.asc"
wget "$SITE/libLASi-$LASI_VERSION.tar.gz"

gpg --verify libLASi-$LASI_VERSION.tar.gz.asc

# Belt and suspenders....

diff libLASi-$LASI_VERSION.tar.gz.asc /home/software/lasi_svn/HEAD/export
diff libLASi-$LASI_VERSION.tar.gz /home/software/lasi_svn/HEAD/export

     Login to sf.net
 
     Go to the file-release area at
     sf.net/projects/lasi/files/lasi/<LASI_VERSION> Source

     (where <LASI_VERSION> stands for whatever you have set
     LASI_VERSION to above)

     Click on the "i" or "info" button to mark the tar.gz file as the
     default file to download for all platforms.

(8)  Commit the tagged version
cd ../lasi_allura_complete
svn commit tags/$LASI_VERSION

(9)  Publicity for the release

     Create a news item for this release largely following previous
     news items (or even identical to them but with a changed title).

     Point your browser to http://sourceforge.net/projects/lasi and
     login.  A news item will then be available on the menu bar.
     Click that, then "new post".

     Enter the title (e.g., libLASI $LASI_VERSION has been released)
     and the text.  The text is in markdown format so copying and
     pasting from a previous news item (using the ctrl-c command on
     the editing area of the old release notes to copy and ctrl-v
     command on the new release notes editing area since normal
     cutting and pasting no longer works) is a very efficient way to
     create the new news item.  After that copy and paste, remember to
     change all occurrences of version references appropriately
     within the text.

     Other publicity:

     None.

(10) Post release tweaking of this file (README.Release_Manager_Cookbook)

     This only needs to be done if the actual procedure followed for
     the release differed in any detail from the previously updated
     instructions in this file.

DONE!  :-)

--- Appendix ---

(A1) GNU Privacy Guard (gpg)
A brief summary of developer relevant gpg commands, see also:
http://dewinter.com/gnupg_howto/english/GPGMiniHowto.html,
man gpg, and http://www.gnupg.org/faq/GnuPG-FAQ.html.

* Configure key-server (if you haven't done that already) by editing
  $HOME/.gnupg/gpg.conf.  Also specify the auto-key-retrieve option
  for convenience.

* List keys on your keyring that have been retrieved or generated so far:

gpg --list-keys irwin

* Search for any previously published keys that you might want to
  revoke.  (Note the search phrase is case insensitive but the search
  is done on the Boolean AND of the terms so the following search would
  miss any key generated in the past by Alan Irwin because of the
  middle initial "W." that is specified for the search).  OTOH, I
  always use my middle initial for publications to reduce name clashes.

gpg --search-keys Alan W. Irwin

* Create a new key:

gpg --gen-key

  With gnupg 1.4.10, I chose the following options when creating a new key:
  
Please select what kind of key you want:
  (1) RSA and RSA (default)

What keysize do you want?
2048 (default)
5-year expiration date.

....

Real name: Alan W. Irwin
Email address: irwin@users.sourceforge.net
Comment: Time Ephemerides key
You selected this USER-ID:
    "Alan W. Irwin (Time Ephemerides key) <irwin@users.sourceforge.net>"


N.B. nameofkey below is the name of the key, usually specified by the
second number after the slash for the first pub line given by
"gpg --list-keys".  For example, the above key gives the following
result:

software@raven> gpg --list-keys irwin
pub   2048R/BB159E92 2011-08-19 [expires: 2016-08-17]
uid                  Alan W. Irwin (Time Ephemerides key) <irwin@users.sourceforge.net>
sub   2048R/C5ECCF77 2011-08-19 [expires: 2016-08-17]

So the name could be BB159E92.  Other possibilities exist as well such
as "irwin", but that might not be unique.

* N.B. Made a mistake in the above.  My SF e-mail address is airwin@....
not irwin@... GRRR.  So fix it.

Under --edit-key command

adduid  (fill in correct e-mail address this time)
uid number (to select uid to work on for further commands
revuid  (revoke bad e-mail one)
primary (to make the new one the primary one, I am not sure that is necessary)
trust  (to make the new one ultimately trusted, again, not sure that is necessary.  N.B. didn't seem to change trust value, but that was just bad output)

save  (to get out again)

When edited the next time showed ultimate trust value for correct id, but
I don't know whether that was the above primary/trust subcommands or
whether those were necessary at all.  It turned out those were not
necessary at all as I later used the above sequence to generate
a libLASi key and a FreeEOS uid key.

* Generate a revocation certificate.  Note this requires the pass phrase
  specified at the time of key generation so keep that pass phrase in
  a safe place or else generate the revocation certificate right after
  generating the key, and keep that certificate in a safe place.  I chose
  the former course (keep the pass phrase safe).  N.B. the options should
  appear below in the order given!

gpg --armor -o nameofkey-revocation.asc --gen-revoke nameofkey

* Publicly revoke old key (from FAQ):

gpg --import old-revocation.asc
gpg --send-keys nameofkey

* Upload your (public) key to GPG key server so that others can obtain it to
verify your signature on the release tarball.
gpg --send-keys nameofkey

gpg --refresh-keys  (to update from the server all keys including your own).

This verified that the bad irwin address was revoked even though
gpg --search-keys Alan W. Irwin

still shows revoked uid as the #1 uid.

(A2) Setting the correct date and time on your computer.

(While it is useful to have the correct time on your computer, this is no 
longer strictly necessary).
Verify that your computer has the right date and time using the command date.
The easiest way to make sure the time and date are correct is to do the 
following:
1. Install the debian ntpdate package.
2. Execute the command "/usr/sbin/ntpdate pool.ntp.org", which you will
   have to do as root.
This will immediately change your system clock. It is not recommended if you
have other apps running on your system that expect time to increase in a
smooth and linear fashion.

If you would like your computer to always have the correct time and date, you 
can install the debian ntp package, which must be properly configured to work.
Some notes about how to do this can be found in the PLplot mailing list 
archive. Look for the thread titled "PLplot 5.7.2 is now available" dated 
Jan 22/23 2007.