Making OpenAFS Releases
The main prerequisites are to have NEWS reflecting the release contents and to have the various places that version numbers are encoded in the tree up to date. This holds whether making a prerelease or a final release, though the specifics vary a little bit between the two cases.
Version numbers
At the time of 1.8.14 (actually earlier but the exact threshold left as an exercise for the reader) the version number is present in five files in the tree: - configure-libafs.ac - configure.ac - src/config/NTMakefile.{amd64_w2k,i386_nt40,i386_w2k}
The autoconf files' versions (MACOS_VERSION) need to be in lockstep, as to the NTMakefiles' versions.
For the MACOS_VERSION, we have a hard milestone that the final release (e.g., 1.8.14) gets the version string of 1.8.14. For prereleases we use the "fc" (final candidate) prefix, so 1.8.14pre1 was 1.8.14fc1. The version schema here is limited to three components, so for our point releases (e.g., 1.8.13.2) we do "development" ("d") releases of the next minor version, so that 1.8.13.2 is reflected as 1.8.14d2, since we need to maintain logical ordering of our versions to get the proper behavior on upgrades.
For the NTMakefile versions (AFSPRODUCT_VER_PATCH) we treat it as a four digit number, subdivided into two two-digit sub-fields. The first sub-field corresponds to our actual minor release version (e.g., for our 1.8.14 it is just "14") and the second sub-field increments for every subsequent prerelease or point release. Note that when we have pre-releases for the OpenAFS minor release, this means that the second sub-field of AFSPRODUCT_VER_PATCH does not align with the point version of subsequent point versions based on that minor release.
Tagging
Once the proper commits are in place, we need to make a tag. This is typically done by someone with permissions to push tags to gerrit (currently just gerrit Administrators, i.e., kaduk). We use a signed tag, though the key used to make the signature is not particularly strongly verified/distributed by our infrastructure otherwise. (It is mentioned in a comment generated by make_www_release.pl but perhaps not elsewhere.)
1.8.14 was tagged as
git tag -s -m 'OpenAFS 1.8.14' openafs-stable-1_8_14 origin/openafs-stable-1_8_x
Be sure to have an up-to-date repo before tagging, and inspect the tag and
the tagged commit (e.g., with git show) before pushing it.
Push the tag:
git push gerrit openafs-stable-1_8_14
Preparing tarballs
Once the tag exists, we need to prepare the official release tarballs. This
is done using the build-tools/make-release script. Typical usage passes a
directory argument, which must already exist. To facilitate interaction
with other tooling (e.g., for website updates), it's easiest to use the
version number as the directory name. For pre-relases, the web tooling
expects the directory to be under a "candidate" directory, so it's helpful
to use that path when generating tarballs in the first place (but of course
the files can be moved later if needed).
mkdir ../1.8.14
build-tools/make-release --last openafs-stable-1_8_13_2 --dir ../1.8.14 openafs-stable-1_8_14
The --last argument is the immediately preceeding final release, whether
minor or point, and the final (positional) argument is the tag name of the
release for which we're producing tarballs.
A small amount of post-processing is needed after running make-release --
the RELNOTES-X.Y.Z file is produced by taking the first bits of NEWS, from
line 1 to the blank line before the previous release. Make sure that you
are taking the NEWS file from the tagged version, rather than whatever
tree happens to be checked out!
Creating volumes
We need to create (RW and RO) volumes in the grand.central.org cell to hold
the release tarballs, mount them, populate them, and vos release them.
The status of which fileservers are present and preferred for use in
grand.central.org is subject to change, of course. While
/afs/grand.central.org/service/partitions does exist, it does not seem to be
current at the time of this writing, so the strategy of "put the new release
where the previous release's volumes are" should suffice; the cell admins
can rebalance if needed.
This step needs to be done by a member of system:administrators -c
grand.central.org
bash:~$ aklog grand.central.org
bash:~$ vos create montana.central.org a sw.openafs.1814 -maxquota 0 -cell grand.central.org
bash:~$ vos addsite montana.central.org a sw.openafs.1814 -cell grand.central.org
bash:~$ vos addsite grand.mit.edu a sw.openafs.1814 -cell grand.central.org
bash:~$ cd /afs/.grand.central.org/software/openafs
bash:/afs/.grand.central.org/software/openafs$ fs mkmount 1.8.14 sw.openafs.1814
bash:/afs/.grand.central.org/software/openafs$ cp ~/openafs/1.8.14/* 1.8.14
bash:/afs/.grand.central.org/software/openafs$ fs copyacl 1.8.13 1.8.14
bash:/afs/.grand.central.org/software/openafs$ vos release sw.openafs.1814 -cell grand.central.org
bash:/afs/.grand.central.org/software/openafs$ vos release sw.openafs -cell grand.central.org
Prerelease versions are in the candidate subdirectory, and the volume
would be named like sw.openafs.1814pre1; the second release would be for
sw.openafs.rc in that case (the candidate directory is in a different
volume).
Note also that we just compress all the numbers from the version into a single stream, and will cope with collisions if they occur.
Updating the website
The website sources are in the openafs-web.git repository, but the infrastructure serving the website lives at CMU and require a remctl trigger to actually fetch and rebuild the live document root.
Most of the changes to the website are made by a script but some manual edits are currently needed. The script has a lot of logic in it that is effectively unused at present, to handle the presence of compiled binaries, source RPMs, and the like in the release volume, but we are not currently distributing compiled binaries from dl.openafs.org for new releases.
If the person preparing the release has access to a trusted RPM-based
system, it is still helpful to run make srpm and distribute that srpm in
the release volume (and get it linked from the website), though.
The script to generate the release page for the website is in the
tools.git repo, at path openafs/make_www_release, but most users of the
script end up with a few local modifications (most notably to the LocalRoot
variable but on occasion also for some other edits to the generated
content).
make_www_release takes a -c ("candidate") argument for prereleases.
Note that make_www_release takes a directory argument (where to store the
releases's files) and the directory must already exist.
bash:x$ cd openafs-web
bash:x/openafs-web$ mkdir release/1.8.14
bash:x/openafs-web$ make_www_release 1.8.14 .
bash:x/openafs-web/release$ ln -s 1.8.14/index.html openafs-1.8.14.html
We also put a news item on the main page (that is, main.html), which in
practice is done by copying the previous release's news item and editing as
needed. Be sure to update the version number all places where it appears
(it appears multiple times on some lines).
bash:$ ${EDITOR} main.html
bash:$ git add main.html release/1.8.14 release/openafs-1.8.14.html
bash:$ git commit
bash:$ git push gerrit HEAD:refs/for/master
Gerrit's "Web Publishers" group has permission to +2 and merge changes to the web repo; this group is managed separately from other permissions used in the process of making a release.
Once the website change has been merged in gerrit, a remctl command is
used to trigger a refresh on the actual web server:
remctl www-01.central.org export_htdocs openafs
This uses Kerberos authentication, with an ACL that is manually managed by the server administrators (once again, separately from all the other things that are done as part of making a release).
It's probably worth loading up the website and checking that the links from the news entry and release page all work (if a volume release was missed or we didn't use the right paths for a prerelease, sometimes they do not).
Email announcement
Once the website is live, we can send an email announcement for the release. This is the last step in the process!
Announcements for regular/final releases are sent To:
openafs-announce@openafs.org with Cc: openafs-info@openafs.org,
openafs-devel@openafs.org; announcements for prereleases are send just
To; openafs-info@openafs.org, openafs-devel@openafs.org. The templates
for release announcements appear below, with placeholders to be
replaced by the actual version and a human-generated summary of what
is in the release. This summary might be taken largely from the website
announcement but there is no technical process to share the text.
It is preferred to have the announcement be OpenPGP-signed, but there is no process or technical requirement to do so.
Template for final releases
``` Subject: OpenAFS %%VERSION%% is available
The OpenAFS maintainers are happy to announce the availability of OpenAFS %%VERSION%%. Source files can be accessed via the web at:
https://www.openafs.org/release/openafs-%%VERSION%%.html
or via AFS at:
UNIX: /afs/grand.central.org/software/openafs/%%VERSION%%/
UNC: \\afs\grand.central.org\software\openafs\%%VERSION%%\
This release includes %%%%
Bug reports should be filed to openafs-bugs@openafs.org.
%%NAME%% for the OpenAFS maintainers ```
Template for prereleases
``` Subject: OpenAFS %%VERSION%% is available
The OpenAFS maintainers are happy to announce the availability of OpenAFS %%VERSION%%. Source files can be accessed via the web at:
https://www.openafs.org/release/openafs-%%VERSION%%.html
or via AFS at:
UNIX: /afs/grand.central.org/software/openafs/%%VERSION%%/
UNC: \\afs\grand.central.org\software\openafs\%%VERSION%%\
This release includes %%%%
Please assist the maintainers by deploying and testing this release and providing positive or negative feedback. Bug reports should be filed to openafs-bugs@openafs.org ; reports of successes should be sent to openafs-info@openafs.org.
%%NAME%% for the OpenAFS maintainers ```