doc/HOWTO-RELEASE

   1 How to make a new release of GNU Stow
   2 =====================================
   3
   4 Prerequisite reading
   5 --------------------
   6
   7 First read the official information for maintainers of GNU software:
   8
   9   https://www.gnu.org/prep/maintain/
  10
  11 Release procedure
  12 -----------------
  13
  14 - Ensure configure.ac contains the number of the new unreleased
  15   version.  This should follow Semantic Versioning as described at:
  16
  17     http://semver.org/
  18
  19 - To make the following steps easier, set the $version shell variable
  20   to the same version number as above, e.g.
  21
  22     version=$( tools/get-version ) && echo $version
  23
  24 - Ensure NEWS contains the latest changes, and that any new
  25   contributors have been added to THANKS.  If necessary, commit
  26   any additions:
  27
  28     git commit -m "Prepare NEWS and THANKS for $version release"
  29
  30 - Check CPAN distribution will work via Module::Build:
  31
  32     - Start from a clean slate:
  33
  34         make maintainer-clean
  35         autoreconf -iv
  36
  37     - Generate stow, chkstow, and lib/Stow.pm via:
  38
  39         eval `perl -V:siteprefix`
  40         automake --add-missing
  41         ./configure --prefix=$siteprefix && make
  42
  43       (N.B. the CPAN distribution will contain these files, whereas
  44       the GNU distribution will not.)
  45
  46     - Make sure all the following commands all run successfully:
  47
  48         perl Build.PL --prefix=/tmp/stow-test
  49         ./Build test
  50         ./Build install
  51         ./Build distcheck
  52         ./Build distmeta
  53         ./Build dist
  54
  55     - Check META.yml and META.json have the new version number.
  56       They already should if the final step of this document was
  57       carried out after the previous release was publised, but
  58       if not:
  59
  60         git commit -m "Bump version to $version"
  61
  62 - Ensure all changes are committed to git.
  63
  64 - Run make distcheck and ensure that everything looks good.
  65   It should generate the distribution files for you.
  66
  67 - Run the tests on various Perl versions via Docker:
  68
  69     ./build-docker.sh
  70     ./test-docker.sh
  71
  72   Obviously if there are any failures, they will need to be fixed
  73   first, and then repeat the above steps.
  74
  75 - At this point we have a release candidate.  Tag the current git HEAD
  76   with the new version number:
  77
  78     git tag -s v$version -m "Release $version"
  79
  80 - Upload the resulting Stow-v7.8.9.tar.gz to CPAN via https://pause.perl.org/
  81
  82 - Wait until PAUSE has accepted the upload as a valid module.  If you
  83   are the maintainer of the module, you should receive two email
  84   notifications: a CPAN upload confirmation, and a PAUSE indexer
  85   report.  This provides some valuable final validation, as learnt the
  86   hard way during the non-release of 2.2.1.
  87
  88 - Push HEAD and tag to savannah and GitHub:
  89
  90     git push savannah master
  91     git push --tags savannah
  92     git push github master
  93     git push --tags github
  94
  95 - Upload the new release to ftp.gnu.org.  This is easiest using gnupload:
  96
  97     - git clone git://git.savannah.gnu.org/gnulib.git
  98     - Copy gnulib/build-aux/gnupload to somewhere on your $PATH
  99     - Run gnupload --to ftp.gnu.org:stow --symlink-regex stow-7.8.9.tar.*
 100
 101 - Regenerate the documentation for the website:
 102
 103     # First check out gnulib repository via:
 104     # git clone git://git.savannah.gnu.org/gnulib.git
 105
 106     # and stow-web CVS repository via the instructions here:
 107     # https://savannah.gnu.org/cvs/?group=stow
 108
 109     # Set paths:
 110     stow_repo=/path/to/stow/git/repo
 111     stow_web_repo=/path/to/stow-web/CVS/working/dir
 112     gnulib_repo=/path/to/gnulib/git/repo
 113
 114     cd $stow_repo
 115     export GENDOCS_TEMPLATE_DIR=$gnulib_repo/doc
 116     $gnulib_repo/util/gendocs.sh \
 117         -s doc/stow.texi \
 118         -o $stow_web_repo/manual \
 119         --email bug-stow@gnu.org \
 120         stow "GNU Stow manual"
 121
 122     cd $stow_web_repo
 123     # Check that the changes look OK
 124     cvs diff
 125     # Then commit
 126     cvs commit -m "Update manual to v$version"
 127
 128 - Update the news section of stow.html in the stow-web CVS repository
 129   to mention the new release.
 130
 131     cd $stow_web_repo
 132     # Check that the changes look OK
 133     cvs diff
 134     # Then commit
 135     cvs commit -m "Update home page to v$version"
 136
 137 - Send release announcements to
 138
 139     - info-stow@gnu.org
 140     - stow-devel@gnu.org
 141     - info-gnu@gnu.org
 142     - https://savannah.gnu.org/news/?group=stow
 143
 144   See http://www.gnu.org/prep/maintain/html_node/Announcements.html for
 145   more on making release announcements.
 146
 147   Excerpts of NEWS can be formatted for inclusion in the email by
 148   selecting the relevant version subtree via M-x org-mark-element,
 149   minus the "* Changes in version x.y.z", running M-x
 150   org-export-dispatch, and exporting as plain text.
 151
 152 - Update the git repositories to the next expected version, so that anyone
 153   who builds from git gets a version of Stow which is higher than the release
 154   which was just cut:
 155
 156     - Increment the patchlevel of the version number in configure.ac.
 157
 158     - Run this again:
 159
 160         version=$( tools/get-version ) && echo $version
 161
 162     - In order to update META.yml and META.json, repeat the same
 163       procedure listed above, starting at "make distclean" and
 164       finishing after "./Build distmeta".
 165
 166     - Check META.yml and META.json now have the new versions.
 167
 168     - git add configure.ac META.{yml,json}
 169
 170     - git commit -m "Bump version to $version for development of next release"
 171
 172     - git push savannah master
 173
 174     - git push github master