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.  If necessary, commit
  25   any additions:
  26
  27     git commit -m "Prepare NEWS for $version release"
  28
  29 - Check CPAN distribution will work via Module::Build:
  30
  31     - Start from a clean slate:
  32
  33         make maintainer-clean
  34         autoreconf -iv
  35
  36     - Generate stow, chkstow, and lib/Stow.pm via:
  37
  38         eval `perl -V:siteprefix`
  39         automake --add-missing
  40         ./configure --prefix=$siteprefix && make
  41         make pdf
  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 published, but
  58       if not:
  59
  60         git add configure.ac META.{yml,json}
  61         git commit -m "Bump version to $version"
  62
  63 - Ensure all changes are committed to git.
  64
  65 - Run make distcheck and ensure that everything looks good.
  66   It should generate the distribution files for you.
  67
  68 - Run the tests on various Perl versions via Docker:
  69
  70     ./build-docker.sh
  71     ./test-docker.sh
  72
  73   Obviously if there are any failures, they will need to be fixed
  74   first, and then repeat the above steps.
  75
  76 - At this point we have a release candidate.  Tag the current git HEAD
  77   with the new version number:
  78
  79     git tag -s v$version -m "Release $version"
  80
  81 - Upload the resulting Stow-v7.8.9.tar.gz to CPAN via https://pause.perl.org/
  82
  83 - Wait until PAUSE has accepted the upload as a valid module.  If you
  84   are the maintainer of the module, you should receive two email
  85   notifications: a CPAN upload confirmation, and a PAUSE indexer
  86   report.  This provides some valuable final validation, as learnt the
  87   hard way during the non-release of 2.2.1.
  88
  89 - Push HEAD and tag to savannah and GitHub:
  90
  91     git push savannah master
  92     git push --tags savannah
  93     git push github master
  94     git push --tags github
  95
  96 - Upload the new release to ftp.gnu.org.  This is easiest using gnupload.
  97   First ensure you have ncftp installed, since gnupload requires this.
  98   Then do:
  99
 100     - git clone git://git.savannah.gnu.org/gnulib.git
 101
 102     - Copy gnulib/build-aux/gnupload to somewhere on your $PATH
 103
 104     - Run gnupload --dry-run --to ftp.gnu.org:stow --symlink-regex stow-7.8.9.tar.{gz,bz2}
 105
 106     - Check that everything looks good, then re-run without the --dry-run option.
 107
 108   See https://www.gnu.org/prep/maintain/html_node/Automated-Upload-Procedure.html
 109   for more details on the upload procedure.
 110
 111 - Regenerate the documentation for the website:
 112
 113     # First check out gnulib repository via:
 114     # git clone git://git.savannah.gnu.org/gnulib.git
 115
 116     # and stow-web CVS repository via the instructions here:
 117     # https://savannah.gnu.org/cvs/?group=stow
 118
 119     # Set paths:
 120     stow_repo=/path/to/stow/git/repo
 121     stow_web_repo=/path/to/stow-web/CVS/working/dir
 122     gnulib_repo=/path/to/gnulib/git/repo
 123
 124     cd $stow_repo
 125     export GENDOCS_TEMPLATE_DIR=$gnulib_repo/doc
 126     $gnulib_repo/util/gendocs.sh \
 127         -s doc/stow.texi \
 128         -o $stow_web_repo/manual \
 129         --email bug-stow@gnu.org \
 130         stow "GNU Stow manual"
 131
 132     cd $stow_web_repo
 133     # Check for any added/removed files, then add/remove as necessary
 134     cvs -nq update
 135     cvs add ...
 136     cvs remove ...
 137
 138     # Check that the changes look OK
 139     cvs diff
 140
 141     # Then commit
 142     cvs commit -m "Update manual to v$version"
 143
 144 - Update the news section of stow.html in the stow-web CVS repository
 145   to mention the new release.
 146
 147     cd $stow_web_repo
 148     # Check that the changes look OK
 149     cvs diff
 150     # Then commit
 151     cvs commit -m "Update home page to v$version"
 152
 153 - Send release announcements to
 154
 155     - info-stow@gnu.org
 156     - stow-devel@gnu.org
 157     - info-gnu@gnu.org
 158     - https://savannah.gnu.org/news/?group=stow
 159
 160   See http://www.gnu.org/prep/maintain/html_node/Announcements.html for
 161   more on making release announcements.
 162
 163   Excerpts of NEWS can be formatted for inclusion in the email by
 164   selecting the relevant version subtree via M-x org-mark-element,
 165   minus the "* Changes in version x.y.z", running M-x
 166   org-export-dispatch, and exporting as plain text.
 167
 168 - Update the git repositories to the next expected version, so that anyone
 169   who builds from git gets a version of Stow which is higher than the release
 170   which was just cut:
 171
 172     - Increment the patchlevel of the version number in configure.ac.
 173
 174     - Run this again:
 175
 176         version=$( tools/get-version ) && echo $version
 177
 178     - In order to update META.yml and META.json, repeat the same
 179       procedure listed above, starting at "make maintainer-clean" and
 180       finishing after "./Build distmeta".
 181
 182     - Check META.yml and META.json now have the new versions.
 183
 184     - git add configure.ac META.{yml,json}
 185
 186     - git commit -m "Bump version to $version for development of next release"
 187
 188     - git push savannah master
 189
 190     - git push github master