diff options
Diffstat (limited to 'RELEASE')
| -rw-r--r-- | RELEASE | 217 |
1 files changed, 217 insertions, 0 deletions
@@ -0,0 +1,217 @@ +Name + Release - instructions for releasing a new version + +Synopsis + Change log, git tag, tarball, LSM, email, and push. + +Description + This are the instructions to release a new official version of + the project. However, these should also be useful for those who + simply want to package a random commit (this is done for example + by Gentoo). For packaging a random commit without an official + release, you only need step (4) "Tarball". + + Dependencies + The following list of dependencies states what the build system + (the makefiles) need to perform the relevant (dist) targets: + + - echo(1) + - expr(1) + - find(1) + - git(1) + - grep(1) + - gzip(1) + - install(1) + - locale(1) + - make(1) - GNU Make is required. + - sed(1) + - sort(1) + - tar(1) - GNU tar is required. + - xargs(1) + - xz(1) + + Apart from that, the following commands are also needed for other + tasks shown below: + + - gpg(1) + - kup(1) + + Steps + (1) Version + + - Decide the version number: + + $ old=6.01 + $ new=6.02 + + (2) Changes + + Fill the <Changes> file. For that you can check older + commits: `git log -p --grep 'Changes: Ready for 6'`. It + needs manual intervention, but in those commit logs you can + check a few commands that will help. + + - Remember to change the version number, the date, and the + location. + + - Remove any headers not used for a specific release + (usually happens with "New and changed links"). + + - The structure is a bit freestyle, but keep it organized. + Check how previous releases did it. + + - Commit: + + $ git add Changes + $ git commit -sm "Changes: Ready for $new" + + (3) Tag + + Create a signed tag. The tag message should note the most + important changes in the version being released, since it + will be read by users and packagers. It should include any + information that is especially relevant for them. Check old + tags: + `git tag | grep 'man-pages-6' | tac | xargs git show --stat` + + - Tag: + + $ git tag -s man-pages-$new + + (4) Tarball + + Creating the tarball will embed in the manual pages both the + version number, and the date of last modification (in the + git repository, the pages have placeholders for the date and + the version). + + You need to create a set of tarballs, sign the .tar archive, + and upload the compressed tarballs to <kernel.org>. + + In case you're creating a tarball for distributing a random + commit, it might be interesting to tweak a few parameters; + check the variables available at <share/mk/dist.mk>, and any + makefiles included by that one. See the "Versions" section + below. + + - Create the tarball: + + $ make -Bj4 dist + + Alternatively, you may want to only create a specific + kind of tarball with one of the following targets: + + $ make -Bj4 dist-tar dist-xz dist-gz + + - Sign the tarball: + + $ cd .tmp/ + $ gpg --detach-sign --armor man-pages-$new.tar + + - Verify the signature: + + $ gpg --verify man-pages-$new.tar{.asc,} + + - Upload the tarball: + + $ kup put man-pages-$new.tar.{xz,asc} \ + /pub/linux/docs/man-pages/ + $ cd .. + + (5) LSM + + Update the <lsm> file. Check old commits: + `git log -p -- lsm`. + + - Update the project version number. + + - Update the release date. + + - Update the tarball name and size. + + - Commit: + + $ git add lsm + $ git commit -sm "lsm: Released $new" + + - Send (email) the lsm file to <lsm@qqx.org> with the + subject "add". + + (6) Email + + Send an announce email to linux-man, LKML, libc-alpha, and + possibly others that might be interested in the release, + such as distribution maintainers, or those who have + contributed to the release. + + The email should contain a mix of the git tag message, the + contents of Changes, and anything else that might be + relevant. Check old emails such as + <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>. + + The subject of the email should be + "man-pages-$new released". + + (7) Changes.old + + Move the contents of <Changes> to <Changes.old>, and prepare + for the next release. + + - Copy contents of <Changes> to <Changes.old>: + + $ (echo; echo) >> Changes.old + $ cat Changes >> Changes.old + + - Empty <Changes>: + + $ git checkout man-pages-$new^^ -- Changes + + - Commit: + + $ git add Changes Changes.old + $ git commit -sm \ + "Start of man-pages-NEXT: Move Changes to Changes.old" + + (8) Push + + You've finished. When you confirm it's good, push to the + git repository. + + - Push: + + $ git push + $ git push korg man-pages-$new + + korg is just my name for the remote. + +Files + Changes, Changes.old + Change log. Includes most relevant changes. + + Makefile, share/mk/dist.mk, share/mk/version.mk + Main makefiles used for releasing (however, others may also be + used by inclusion). + + lsm + Linux software map. See also <https://lsm.qqx.org/>. + + .tmp/man-pages-<version>.tar{,.xz,.gz} + Generated tarballs. You can generate all with 'make -B dist', or + generate only some of them, with 'make -B dist-tar', + 'make -B dist-xz', or 'make -B dist-gz'. + +Versions + Use the DISTVERSION variable when running make(1) to specify a + version different than the default, which is generated with + git-describe(1). This needs to be done from the git repository, + and won't work from an extracted tarball. + + $ make -B dist-xz DISTVERSION=6.01+43 + +Caveats + The version and date of last modification for each page is + hardcoded by the Makefile into the pages when the tarball is + generated. This means that it's not possible to generate a valid + tarball from another extracted tarball, since the version and + date will not be updated. Tarballs need to be created from the + git(1) repository. |