-Instructions for releasing a new version.
-=========================================
+Name
+ Release - instructions for releasing a new version
-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".
+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".
-1) Version
-----------
+ Steps
+ (1) Version
-Decide the version number:
+ - Decide the version number:
- $ old=6.01
- $ new=6.02
+ $ old=6.01
+ $ new=6.02
+ (2) Changes
-2) Changes
-----------
+ Fill the <Changes> file. For that you can check older commits,
+ like d4e80a7748 "Changes: Ready for 6.01". It needs manual
+ intervention, but in that commit log you can check a few commands
+ that will help.
-Fill the <Changes> file. For that you can check older commits, like
-d4e80a7748 "Changes: Ready for 6.01". It needs manual intervention,
-but in that commit log you can check a few commands that will help.
+ - Remember to change the version number, the date, and the
+ location.
-- 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").
-- 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.
+ man-pages-6.00 was a huge release, so it might help to check it:
+ 51228378bec7 "Changes: Ready for 6.00".
-- The structure is a bit freestyle, but keep it organized.
- man-pages-6.00 was a huge release, so it might help to check it:
- 51228378bec7 "Changes: Ready for 6.00".
+ - Commit:
-- Commit:
+ $ git add Changes
+ $ git commit -sm "Changes: Ready for ${new}"
- $ 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 such as
+ 'man-pages-6.00' or 'man-pages-6.01'.
-3) Tag
-------
+ - 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 such as 'man-pages-6.00' or
-'man-pages-6.01'.
+ $ git tag -s man-pages-${new}
-- Tag:
+ (4) Tarball
- $ git tag -s man-pages-${new}
+ 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>.
-4) Tarball
-----------
+ 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 <lib/dist.mk>, and any makefiles
+ included by that one. See the "Versions" section below.
-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).
+ - Create the tarball:
-You need to create a set of tarballs, sign the .tar archive, and upload
-the compressed tarballs to <kernel.org>.
+ $ make dist
-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 <lib/dist.mk>, and any makefiles included by that one.
+ Since it takes a few seconds, you may prefer to run it in
+ parallel:
-- Create the tarball:
+ $ make -j dist
- $ make dist
+ Alternatively, you may want to only create a specific kind of
+ tarball with one of the following targets:
-- Sign the tarball:
+ $ make dist-tar dist-xz dist-gz
- $ cd tmp/
- $ gpg --detach-sign --armor man-pages-${new}.tar
+ - Sign the tarball:
-- Upload the tarball:
+ $ cd tmp/
+ $ gpg --detach-sign --armor man-pages-${new}.tar
- $ kup put man-pages-${new}.tar.xz man-pages-${new}.tar.asc \
- /pub/linux/docs/man-pages/
- $ cd ..
+ - Upload the tarball:
+ $ kup put man-pages-${new}.tar.xz man-pages-${new}.tar.asc \
+ /pub/linux/docs/man-pages/
+ $ cd ..
-5) LSM
-------
+ (5) LSM
-Update the <lsm> file. Check old commits, like
-c11cb1ca844d "Ready for 6.01".
+ Update the <lsm> file. Check old commits, like
+ c11cb1ca844d "Ready for 6.01".
-- Update the project version number.
+ - Update the project version number.
-- Update the release date.
+ - Update the release date.
-- Update the tarball name and size.
+ - Update the tarball name and size.
-- Commit:
+ - Commit:
- $ git add lsm
- $ git commit -sm "lsm: Released ${new}"
+ $ git add lsm
+ $ git commit -sm "lsm: Released ${new}"
-- Send (email) the lsm file to <lsm@qqx.org> with the subject "add".
+ - Send (email) the lsm file to <lsm@qqx.org> with the subject
+ "add".
+ (6) Email
-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.
-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 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".
-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.
-7) Changes.old
---------------
+ - Copy contents of <Changes> to <Changes.old>:
-Move the contents of <Changes> to <Changes.old>, and prepare for the
-next release.
+ $ (echo; echo) >> Changes.old
+ $ cat Changes >> Changes.old
-- Copy contents of <Changes> to <Changes.old>:
+ - Empty <Changes>:
- $ (echo; echo) >> Changes.old
- $ cat Changes >> Changes.old
+ $ git checkout man-pages-${new}^^ -- Changes
-- Empty <Changes>:
+ - Commit:
- $ git checkout man-pages-${new}^^ -- Changes
+ $ git add Changes Changes.old
+ $ git commit -sm \
+ "Start of man-pages-NEXT: Move Changes to Changes.old"
-- Commit:
+ (8) Push
- $ git add Changes Changes.old
- $ git commit -sm "Start of man-pages-NEXT: Move Changes to Changes.old"
+ You've finished. When you confirm it's good, push to the git
+ repository.
+ - Push:
-8) Push
--------
-
-You've finished. When you confirm it's good, push to the git repository.
-
-- Push:
-
- $ git push
- $ git push man-pages-${new}
+ $ git push
+ $ git push man-pages-${new}
projects / thirdparty / man-pages.git / commitdiff
