RELEASE

   1 Instructions for releasing a new version.
   2 =========================================
   3
   4 This are the instructions to release a new official version of the
   5 project.  However, these should also be useful for those who simply want
   6 to package a random commit (this is done for example by Gentoo).  For
   7 packaging a random commit without an official release, you only need
   8 step 5 "Tarball".
   9
  10
  11 1) Version
  12 ----------
  13
  14 Decide the version number:
  15
  16     $ old=6.01
  17     $ new=6.02
  18
  19
  20 2) Changes
  21 ----------
  22
  23 Fill the Changes file.  For that you can check older commits, like
  24 d4e80a7748 "Changes: Ready for 6.01".  It needs manual intervention,
  25 but in that commit log you can check a few commands that will help.
  26
  27 - Remember to change the version number, the date, and the location.
  28
  29 - Remove any headers not used for a specific release (usually happens
  30   with "New and changed links").
  31
  32 - The structure is a bit freestyle, but keep it organized.
  33   man-pages-6.00 was a huge release, so it might help to check it:
  34   51228378bec7 "Changes: Ready for 6.00".
  35
  36 - Commit:
  37
  38     $ git add Changes
  39     $ git commit -sm "Changes: Ready for ${new}"
  40
  41
  42 3) Tag
  43 ------
  44
  45 Create a signed tag.  The tag message should note the most important
  46 changes in the version being released, since it will be read by users
  47 and packagers.  It should include any information that is especially
  48 relevant for them.  Check old tags such as 'man-pages-6.00' or
  49 'man-pages-6.01'.
  50
  51 - Tag:
  52
  53     $ git tag -s man-pages-${new}
  54
  55
  56 4) Tarball
  57 ----------
  58
  59 Creating the tarball will embed in the manual pages both the version
  60 number, and the date of last modification (in the git repository, the
  61 pages have placeholders for the date and the version).
  62
  63 You need to create a set of tarballs, sign the .tar archive, and upload
  64 the compressed tarballs to <kernel.org>.
  65
  66 In case you're creating a tarball for distributing a random commit, it
  67 might be interesting to tweak a few parameters; check the variables
  68 available at <lib/dist.mk>, and any makefiles included by that one.
  69
  70 - Create the tarball:
  71
  72     $ make dist
  73
  74 - Sign the tarball:
  75
  76     $ cd tmp/
  77     $ gpg --detach-sign --armor man-pages-${new}.tar
  78
  79 - Upload the tarball:
  80
  81     $ kup put man-pages-${new}.tar.xz man-pages-${new}.tar.asc \
  82               /pub/linux/docs/man-pages/
  83     $ cd ..
  84
  85
  86 5) lsm
  87 ------
  88
  89 Rename the file with the version that has been released, and update the
  90 contents.  Check old commits, like c11cb1ca844d "Ready for 6.01".
  91
  92 - Update the version number (and also in the tarball name).
  93
  94 - Update the release date.
  95
  96 - Update the tarball size.
  97
  98 - Rename the file:
  99
 100     $ mv man-pages-${old}.lsm man-pages-${new}.lsm
 101
 102 - Commit:
 103
 104     $ git add man-pages-${old}.lsm
 105     $ git add man-pages-${new}.lsm
 106     $ git commit -sm "lsm: Released ${new}"
 107
 108 - Send (email) the .lsm file to <lsm@qqx.org> with the subject "add".
 109
 110
 111 6) Email
 112 --------
 113
 114 Send an announce email to linux-man, LKML, libc-alpha, and possibly
 115 others that might be interested in the release, such as distribution
 116 maintainers, or those who have contributed to the release.
 117
 118 The email should contain a mix of the git tag message, the contents of
 119 Changes, and anything else that might be relevant.  Check old emails
 120 such as
 121 <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>.
 122
 123 The subject of the email should be "man-pages-${new} released".
 124
 125
 126 7) Changes.old
 127 --------------
 128
 129 Move the contents of Changes to Changes.old, and prepare for the next
 130 release.
 131
 132 - Copy contents of Changes to Changes.old:
 133
 134     $ (echo; echo) >> Changes.old
 135     $ cat Changes >> Changes.old
 136
 137 - Empty Changes:
 138
 139     $ git checkout man-pages-${new}^^ -- Changes
 140
 141 - Commit:
 142
 143     $ git add Changes Changes.old
 144     $ git commit -sm "Start of man-pages-NEXT: Move Changes to Changes.old"
 145
 146
 147 8) Push
 148 -------
 149
 150 You've finished.  When you confirm it's good, push to the git repository.
 151
 152 - Push:
 153
 154     $ git push
 155     $ git push man-pages-${new}