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 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 5-10 minutes, so go have a cup of coffee. When you come back, the built tarballs and checksum files will be in ~pgsql/output/.

We generally restrict immediate access to the tarballs to members of the pgsql-packagers list, especially when security fixes are involved. Therefore, the next step is to select a random subdirectory name and put the new tarballs there:

SUBDIR=`dd if=/dev/urandom count=1 bs=32 2>/dev/null | sha1sum | awk '{print $1}'`
mkdir ~pgsql/staging/$SUBDIR
mv ~pgsql/output/* ~pgsql/staging/$SUBDIR
echo See https://borka.postgresql.org/staging/$SUBDIR/

At this point, the files should be web-accessible at the URL printed by the last step.

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.

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.

Building and making PDFs available

Soon after tagging, PDFs need to be built and made available.

The details for these steps are on Redmine here.

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.