Release process

This page documents the Postgres release-wrapping process. See src/tools/RELEASE_CHANGES for context, but this is meant to be a detailed checklist for whoever is wrapping tarballs.

Prerequisites

• You must have the appropriate autoconf version installed for each Postgres branch you plan to wrap. For currently-supported branches, that's
  • 2.69 for PG 9.4 and up
  • 2.63 for PG 9.0 - 9.3

To ensure we get the same results no matter who does version stamping, please use exactly the GNU-released autoconf versions; avoid distro-provided packages as they may contain assorted patches. Even if those patches are for the better, we don't want variation in our results. I tend to grab the GNU tarballs and tell them to install with

 ./configure --prefix=/usr/local/autoconf-N.NN

then put the appropriate /usr/local/autoconf-N.NN/bin into my PATH before stamping.

Before-wrap tasks

• Update tzdata files if appropriate; see src/timezone/README.
• Update release notes as appropriate.
• Update translation files from the separate translation repository (XXX reference for this process?)

It's best to not leave these things for the very last minute, so that we can get some buildfarm cycles verifying that nothing's horribly broken.

Version stamping

This can be done by any committer, assuming the appropriate autoconf version is installed locally. The heavy lifting is all done by src/tools/version_stamp.pl, but in detail the process looks like this for each branch:

git pull
git checkout REL_x_STABLE
src/tools/version_stamp.pl y
run appropriate autoconf version
run appropriate autoheader version  # optional, shouldn't change anything if committers have been careful
rm -rf autom4te.cache
git diff  # optional but good to check that nothing looks insane
git commit -a -m "Stamp x.y."    # or "Stamp xbetaN."
git show  # make a note of the commit hash, for use below
git push

version_stamp.pl will insist that y be a number or something else appropriate (such as beta2), but it doesn't check further than that. The main thing I generally look for at the git diff step is that I correctly chose the next higher minor release number for this branch. Also, if you see anything except version-numbering-related diffs, it likely means that you or somebody else used an unapproved autoconf version; check closely before proceeding!

Please follow exactly the commit message format shown above for version-stamping commits.

Tarball construction

In principle this could be done anywhere, but again there's a concern about reproducibility, since the results may vary depending on installed bison, flex, docbook, etc versions. Current practice is to always do this as pgsql on borka.postgresql.org, so it can only be done by people who have a login there. In detail:

ssh borka.postgresql.org
sudo -u pgsql -i

mk-release-bundle commit-hash [ commit-hash ... ]

where the commit-hashes are those of the stamping commits, or whatever you want to wrap on each branch. As indicated, you can specify multiple builds with one call of the script, and when releasing back branches that's the way to do it. Each tarball build takes several minutes, so go have a cup of coffee.

We generally restrict immediate access to the tarballs to members of the pgsql-packagers list, especially when security fixes are involved. Therefore, the mk-release-bundle script creates a randomly-named subdirectory and puts the new tarballs there, along with some other stuff such as checksum files and generated PDF documentation. The script will print something like

 See https://borka.postgresql.org/staging/$SUBDIR/

At this point, the files should be web-accessible at that URL.

What I like to do next is download the tarballs to my own machine and diff them against my own git checkout, and do a spot check or two on the generated documentation. (I don't recall that this has ever actually turned up a problem, but it gives me a warm fuzzy feeling.)

In v17 and later, the tarball contents should trivially match a bare git checkout. In earlier branches, the tarball will also contain a bunch of generated files. It should match the state of your git checkout after

 ./configure; make distprep; make distclean

However, the generated files are very likely to differ if you don't have the identical bison, flex, etc tool versions that borka has, so allow for that.

One way or another, once you are satisfied that the tarballs are OK, notify pgsql-packagers that the files are available, making sure to mention the secret URL printed above. Something like:

To: pgsql-packagers
Subject: Postgres minor-release (or xbetaN) tarballs are up
Body:

... at
https://borka.postgresql.org/staging/$SUBDIR/

As usual, public announcement will be on Thursday.

Final version tagging

At this point we generally give the packagers at least 24 hours to verify that packages can be built from the tarballs. (And yes, they've found problems in the past.) In event of disaster, fix code as needed then repeat the wrap process, with or without a version number bump as seems appropriate.

Whenever the dust seems reasonably well settled, publish tags into the Postgres git repo to mark which commit each release was actually built from. Pushing a tag is more or less irreversible, so don't do this until packager preliminary testing is over:

git tag REL_x_y commit-hash

# optional, but a good idea to make sure you're not going to push any private tags
git push -n --tags

git push --tags

Again, please follow past convention as to the exact formatting of the tag names. You can do this in your personal checkout, it doesn't need to be done on borka.

Release-day tasks

When the announcement day arrives, the tarballs need to be copied from the staging directory on borka to appropriate places on the project's public servers.

After that, publish the release announcement.

The details for these steps are on Redmine here.

Roles

The process described above involves a number of tasks, usually performed by several people, each playing a different role.

In summary the tasks are:

1. Update tzdata files
2. Update release notes
3. Update translation files
4. Version stamping
5. Tarball construction
6. Release-day sysadmin
7. Release-day webmaster

Generally the tasks are distributed to roles as follows, although other assignments are possible:

1. Construction Lead - performs tasks #1, 4, and 5
2. Release notes Lead - performs task #2
3. Translation Lead - performs task #3
4. Sysadmin - performs task #6
5. Webmaster - performs task #7