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 that the changes look OK
 132     cvs diff
 133     # Then commit
 134     cvs commit -m "Update manual to v$version"
 135
 136 - Update the news section of stow.html in the stow-web CVS repository
 137   to mention the new release.
 138
 139     cd $stow_web_repo
 140     # Check that the changes look OK
 141     cvs diff
 142     # Then commit
 143     cvs commit -m "Update home page to v$version"
 144
 145 - Send release announcements to
 146
 147     - info-stow@gnu.org
 148     - stow-devel@gnu.org
 149     - info-gnu@gnu.org
 150     - https://savannah.gnu.org/news/?group=stow
 151
 152   See http://www.gnu.org/prep/maintain/html_node/Announcements.html for
 153   more on making release announcements.
 154
 155   Excerpts of NEWS can be formatted for inclusion in the email by
 156   selecting the relevant version subtree via M-x org-mark-element,
 157   minus the "* Changes in version x.y.z", running M-x
 158   org-export-dispatch, and exporting as plain text.
 159
 160 - Update the git repositories to the next expected version, so that anyone
 161   who builds from git gets a version of Stow which is higher than the release
 162   which was just cut:
 163
 164     - Increment the patchlevel of the version number in configure.ac.
 165
 166     - Run this again:
 167
 168         version=$( tools/get-version ) && echo $version
 169
 170     - In order to update META.yml and META.json, repeat the same
 171       procedure listed above, starting at "make distclean" and
 172       finishing after "./Build distmeta".
 173
 174     - Check META.yml and META.json now have the new versions.
 175
 176     - git add configure.ac META.{yml,json}
 177
 178     - git commit -m "Bump version to $version for development of next release"
 179
 180     - git push savannah master
 181
 182     - git push github master