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