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