Merge pull request #215 from robbat2/robbat2/release-process

build: document & improve release process

Author: robbat2

Docker.autogen

@@ -5,6 +5,7 @@ RUN apt update && \
 		automake \
 		gettext \
 		libtool \
+		gawk \
 		pkg-config
 VOLUME /workdir
 ENTRYPOINT cd /workdir && /bin/sh autogen.sh && ./configure -C && make distclean

Makefile.am

@@ -194,25 +194,41 @@ EXTRA_DIST = \
 	.travis.yml
 
 EXTENSIONS = gz bz2 lz lzma xz tarZ shar zip
-HASHES = sha1 sha256 sha512
+HASHES = sha256 sha512
 
+# Generate clearsigned checksum files.
+# Generate detached signatures of the tarballs.
 sign:
 	$(AM_V_GEN)for e in $(EXTENSIONS); do \
 		if [ -f radvd-$(VERSION).tar.$$e ]; then \
+			gpg --armor --sign --detach-sign radvd-$(VERSION).tar.$$e; \
 			for h in $(HASHES); do \
-				$${h}sum radvd-$(VERSION).tar.$$e > radvd-$(VERSION).tar.$$e.$$h; \
+				$${h}sum --tag radvd-$(VERSION).tar.$$e > radvd-$(VERSION).tar.$$e.$$h || exit 1; \
+				gpg --clear-sign radvd-$(VERSION).tar.$$e.$$h || exit 1; \
+				mv -f radvd-$(VERSION).tar.$$e.$$h.asc radvd-$(VERSION).tar.$$e.$$h || exit 1; \
 			done; \
-			gpg -sba radvd-$(VERSION).tar.$$e; \
 		fi; \
 	done
 
+# Verify clearsigned checksum files.
+# Verify detached signatures of the tarballs.
+#
+# Be careful to verify the clearsign, take ONLY the signed part, and then
+# verify the checksum contained in that (ignore checksums OUTSIDE the
+# clearsigned part).
 verify:
 	$(AM_V_GEN)for e in $(EXTENSIONS); do \
 		if [ -f radvd-$(VERSION).tar.$$e ]; then \
+			gpg --verify radvd-$(VERSION).tar.$$e.asc; \
 			for h in $(HASHES); do \
-				$${h}sum -c radvd-$(VERSION).tar.$$e.$$h; \
+				rm -f radvd-$(VERSION).tar.$$e.$$h.verified || exit 1; \
+				gpg --output radvd-$(VERSION).tar.$$e.$$h.verified --verify radvd-$(VERSION).tar.$$e.$$h || exit 1; \
+				if ! $${h}sum -c radvd-$(VERSION).tar.$$e.$$h.verified ; then \
+					rm -f radvd-$(VERSION).tar.$$e.$$h.verified; \
+					exit 1; \
+				fi; \
+				rm -f radvd-$(VERSION).tar.$$e.$$h.verified; \
 			done; \
-			gpg --verify radvd-$(VERSION).tar.$$e.asc; \
 		fi; \
 	done
 
@@ -233,6 +249,8 @@ html:
 
 packages:
 	@if [[ "$$(git diff | wc -l)" != "0" ]] ; then printf "\n\n\tYou have local changes in the working copy...\n\n\n" && git diff && false ; fi
+	@if [[ "$$(git rev-parse HEAD)" != "$$(git rev-parse v$(VERSION)^{commit})" ]] ; then printf "\n\n\tv$(VERSION) tag missing, or not checked out...\n\n\n" && false ; fi
+	rm -f radvd-$(VERSION).tar*
 	$(MAKE) dist-gzip
 	rm -rf radvd-$(VERSION)
 	tar zfx radvd-$(VERSION).tar.gz
@@ -242,7 +260,6 @@ packages:
 	$(MAKE) sign
 	$(MAKE) verify
 	$(MAKE) html
-	@if [[ "$$(git rev-parse HEAD)" != "$$(git rev-parse v$(VERSION))" ]] ; then printf "\n\n\tv$(VERSION) tag missing, or not checked out...\n\n\n" && false ; fi
 	@printf "\n\n\tDont forget to push the v$(VERSION) tag and this branch to origin (git push origin v$(VERSION) master)\n\n\n"
 
 

RELEASE-PROCESS.md

@@ -0,0 +1,89 @@
+# Rough release process
+
+## Update `CHANGES`
+
+Go through `git log` and ensure that each relevant change is documented in
+the `CHANGES file.
+
+## Ensure version consistency
+
+The version identifier needs to be consistent amongst the `CHANGES` file, the
+`configure.ac` file, and the git tag. First, determine the currently-configured
+version identifier, such as by running:
+
+```
+grep AC_INIT configure.ac | cut -d[ -f 2 | cut -d] -f 1
+grep Release CHANGES | head -1
+```
+
+When preparing a release candidate build, the version string should end with
+`_rcN`, where N is the candidate build number.
+
+Conventionally, the `CHANGES` file will contain a string in the format
+`v<version>`, such as `v2.20_rc1` or `v2.20`, while the git tag and
+`configure.ac` file will contain a string in the format `<version>`, such as
+`2.20_rc1` or `2.20.`
+
+Edit the `CHANGES` file and note the new version identifier.
+
+## Update `configure.ac`
+
+After manually updating the `CHANGES` file, update the `configure.ac` file
+with a matching version identifier, such as:
+
+```
+export VERSION="$(grep Release CHANGES | head -1 | sed s/'.*Release v'//g)"
+echo "New version identifier is: $VERSION"
+sed -i -e "/^AC_INIT/s,\[.*\],[$VERSION],g" configure.ac
+```
+
+## Validate, commit, and tag
+
+Next, examine the changes to ensure accuracy:
+
+```
+git diff CHANGES configure.ac
+```
+
+If everything looks good, commit the changes and create the tag. Note that
+this will create a signed tag, so ensure that you have GPG configured
+appropriately.
+
+```
+git commit -s -m "Release ${VERSION}" CHANGES configure.ac
+git tag -s v${VERSION} -m "$VERSION"
+```
+
+## Build release archives
+
+### Clean up Docker environment
+
+To build the release archives, first delete the container manually to ensure
+the build works with a clean container (this command may fail if hte container
+does not exist):
+
+```
+docker rmi radvd-autogen:latest
+```
+
+### Perform a package build
+
+The `autogen-container.sh` script will run `autoreconf` in a clean environment.
+Afterward, the `./configure` script can be run in order to configure the build
+environment. Finally, `make packages` will create package archives suitable
+for release.
+
+```
+./autogen-container.sh
+./configure
+make packages
+```
+
+### Release the new version on GitHub
+
+To perform this step, first install and configure the
+[GitHub CLI](https://cli.github.com/).
+
+```
+gh release create v${VERSION} radvd-${VERSION}.tar.{xz,gz}{,.asc,.sha256,.sha512}`
+```