RELEASE

   1 Name
   2        Release - instructions for releasing a new version
   3
   4 Synopsis
   5        Change log, git tag, tarball, LSM, email, and push.
   6
   7 Description
   8        This are the instructions to release a new official version of
   9        the project.  However, these should also be useful for those who
  10        simply want to package a random commit (this is done for example
  11        by Gentoo).  For packaging a random commit without an official
  12        release, you only need step (4) "Tarball".
  13
  14    Dependencies
  15        The following list of dependencies states what the build system
  16        (the makefiles) need to perform the relevant (dist) targets:
  17
  18        -  echo(1)
  19        -  expr(1)
  20        -  find(1)
  21        -  git(1)
  22        -  grep(1)
  23        -  gzip(1)
  24        -  install(1)
  25        -  locale(1)
  26        -  make(1) - GNU Make is required.
  27        -  sed(1)
  28        -  sort(1)
  29        -  tar(1) - GNU tar is required.
  30        -  xargs(1)
  31        -  xz(1)
  32
  33        Apart from that, the following commands are also needed for other
  34        tasks shown below:
  35
  36        -  gpg(1)
  37        -  kup(1)
  38
  39    Steps
  40        (1)  Version
  41
  42             -  Decide the version number:
  43
  44                    $ old=6.01
  45                    $ new=6.02
  46
  47        (2)  Changes
  48
  49             Fill the <Changes> file.  For that you can check older
  50             commits: `git log -p --grep 'Changes: Ready for 6'`.  It
  51             needs manual intervention, but in those commit logs you can
  52             check a few commands that will help.
  53
  54             -  Remember to change the version number, the date, and the
  55                location.
  56
  57             -  Remove any headers not used for a specific release
  58                (usually happens with "New and changed links").
  59
  60             -  The structure is a bit freestyle, but keep it organized.
  61                Check how previous releases did it.
  62
  63             -  Commit:
  64
  65                    $ git add Changes
  66                    $ git commit -sm "Changes: Ready for $new"
  67
  68        (3)  Tag
  69
  70             Create a signed tag.  The tag message should note the most
  71             important changes in the version being released, since it
  72             will be read by users and packagers.  It should include any
  73             information that is especially relevant for them.  Check old
  74             tags:
  75             `git tag | grep 'man-pages-6' | tac | xargs git show --stat`
  76
  77             -  Tag:
  78
  79                    $ git tag -s man-pages-$new
  80
  81        (4)  Tarball
  82
  83             Creating the tarball will embed in the manual pages both the
  84             version number, and the date of last modification (in the
  85             git repository, the pages have placeholders for the date and
  86             the version).
  87
  88             You need to create a set of tarballs, sign the .tar archive,
  89             and upload the compressed tarballs to <kernel.org>.
  90
  91             In case you're creating a tarball for distributing a random
  92             commit, it might be interesting to tweak a few parameters;
  93             check the variables available at <share/mk/dist.mk>, and any
  94             makefiles included by that one.  See the "Versions" section
  95             below.
  96
  97             -  Create the tarball:
  98
  99                    $ make -Bj4 dist
 100
 101                Alternatively, you may want to only create a specific
 102                kind of tarball with one of the following targets:
 103
 104                    $ make -Bj4 dist-tar dist-xz dist-gz
 105
 106             -  Sign the tarball:
 107
 108                    $ cd .tmp/
 109                    $ gpg --detach-sign --armor man-pages-$new.tar
 110
 111             -  Verify the signature:
 112
 113                    $ gpg --verify man-pages-$new.tar{.asc,}
 114
 115             -  Upload the tarball:
 116
 117                    $ kup put man-pages-$new.tar.{xz,asc} \
 118                              /pub/linux/docs/man-pages/
 119                    $ cd ..
 120
 121        (5)  LSM
 122
 123             Update the <lsm> file.  Check old commits:
 124             `git log -p -- lsm`.
 125
 126             -  Update the project version number.
 127
 128             -  Update the release date.
 129
 130             -  Update the tarball name and size.
 131
 132             -  Commit:
 133
 134                    $ git add lsm
 135                    $ git commit -sm "lsm: Released $new"
 136
 137             -  Send (email) the lsm file to <lsm@qqx.org> with the
 138                subject "add".
 139
 140        (6)  Email
 141
 142             Send an announce email to linux-man, LKML, libc-alpha, and
 143             possibly others that might be interested in the release,
 144             such as distribution maintainers, or those who have
 145             contributed to the release.
 146
 147             The email should contain a mix of the git tag message, the
 148             contents of Changes, and anything else that might be
 149             relevant.  Check old emails such as
 150             <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>.
 151
 152             The subject of the email should be
 153             "man-pages-$new released".
 154
 155        (7)  Changes.old
 156
 157             Move the contents of <Changes> to <Changes.old>, and prepare
 158             for the next release.
 159
 160             -  Copy contents of <Changes> to <Changes.old>:
 161
 162                    $ (echo; echo) >> Changes.old
 163                    $ cat Changes >> Changes.old
 164
 165             -  Empty <Changes>:
 166
 167                    $ git checkout man-pages-$new^^ -- Changes
 168
 169             -  Commit:
 170
 171                    $ git add Changes Changes.old
 172                    $ git commit -sm \
 173                      "Start of man-pages-NEXT: Move Changes to Changes.old"
 174
 175        (8)  Push
 176
 177             You've finished.  When you confirm it's good, push to the
 178             git repository.
 179
 180             -  Push:
 181
 182                    $ git push
 183                    $ git push korg man-pages-$new
 184
 185                korg is just my name for the remote.
 186
 187 Files
 188    Changes, Changes.old
 189        Change log.  Includes most relevant changes.
 190
 191    GNUmakefile, share/mk/dist.mk, share/mk/version.mk
 192        Main makefiles used for releasing (however, others may also be
 193        used by inclusion).
 194
 195    lsm
 196        Linux software map.  See also <https://lsm.qqx.org/>.
 197
 198    .tmp/man-pages-<version>.tar{,.xz,.gz}
 199        Generated tarballs.  You can generate all with 'make -B dist', or
 200        generate only some of them, with 'make -B dist-tar',
 201        'make -B dist-xz', or 'make -B dist-gz'.
 202
 203 Versions
 204        Use the DISTVERSION variable when running make(1) to specify a
 205        version different than the default, which is generated with
 206        git-describe(1).  This needs to be done from the git repository,
 207        and won't work from an extracted tarball.
 208
 209            $ make -B dist-xz DISTVERSION=6.01+43
 210
 211 Caveats
 212        The version and date of last modification for each page is
 213        hardcoded by the Makefile into the pages when the tarball is
 214        generated.  This means that it's not possible to generate a valid
 215        tarball from another extracted tarball, since the version and
 216        date will not be updated.  Tarballs need to be created from the
 217        git(1) repository.