UpdateReleaseDrafting
Drafting Update Releases
This is a set of guidelines for drafting update release (minor releases) announcements for PostgreSQL.
There are two types of update releases: cumulative bug-fix releases, and security releases. They are distinguished by whether or not there is a CVE-worthy security vulnerability patched in the release. Depending on that, the drafting process for update release announcement is different. In order to determine which type of release you are preparing, you need to ask a member of the PostgreSQL Security Team around 2 weeks before the update release.
Update releases normally happen on a Thursday, with tarballs being wrapped on an Monday. The rest of this guide assumes that this is the schedule.
Cumulative Bug-Fix Releases
These are minor releases in which several issues are fixed, but there are no security issues big enough to warrant a CVE. Usually they come out because either (a) we're fixing a data corruption or serious crash bug, or (b) we've accumulated 3 months of bug fixes without anything else happening. Here are the steps to draft one of these releases:
Schedule
One to two weeks out
You need to find out about the major fixes in the release:
- Determine if any issues fixed in the release are urgent, such as serious data corruption bugs.
- Determine if any changes in the update require action by users or special explanations, such as for backwards compatibility issues.
- Determine if there are special announcements to include in the release, such as the EOL of an older version.
Having determined the above, you can begin drafting the release (see below).
Friday before the release
- Complete the draft except for the list of miscellaneous issues fixed.
- Notify the Regional Contacts that there is an update release coming, and any major issues which will be fixed in it.
Monday of release week (US Time)
Once that update version is branched, examine the release notes and the list of git commits in order to assemble a list of "additional bug fixes" for the release. Finish the release draft. Send links to the release draft to Hackers in order to have people double-check your descriptions and relevancy of the fix list.
Tuesday Night or Wednesday Morning (US Time)
- Incorporate Hacker feedback.
- Produce a TXT version based on the MD release.
- Check it in and let Magnus Hagander and Dave Page know that it is complete.
- Send out the final version to the Regional Contacts
Thursday Morning
Magnus or Dave will send out the release.
After the release
Move the announcement to /archive/
Release Drafting
Update releases should be based on the "update release template" in the git.postgresql.org/press repository. Contributors who are collaborating on the release should create a file in the update_releases/current/ subdirectory, and collaborate there. Policies for branching and/or forking are up to the contributors involved.
There are two files produced for each release, a markdown file which is the version which goes on News on the website, and a Text version which is what gets sent by email. Generally it's easiest to work on the markdown version, and convert it to text when the markdown version is final.
Urgency of Release
We use specific language to say how quickly users need to apply a release. This is as follows:
All users of the affected versions are strongly urged to apply the update immediately: release contains a high-exposure security hole or critical data loss bug which affects all users. Stop reading, declare a downtime, and apply the update now. Fortunately, we've only had one of these in the last 6 years.
All users should apply this update as soon as possible: the release contains one or more security holes and/or major data loss bugs expected to affect most users. Schedule a downtime tonight or this weekend and apply the update.
All users of _________ should apply this update immediately/as soon as possible: the same as above, but only for users of a particular feature or extension.
Users should apply this update at the next available opportunity: the release contains some low-risk security holes and/or serious data loss bugs which only occur under certain circumstances. Updating to this release shouldn't be put off for more than a couple weeks, but you can wait for a good low-traffic window to take the downtime.
Users should update at the next regular maintenance window/scheduled downtime: this update contains nothing critical or even serious for most users; it's largely a cumulative collection of bugfixes. The update should be added to the general queue of OS, library and application updates for the production servers.
Significant Fixes
Some, but not all, bugfix releases have one or more major issues which are patched in them, and suggest a more detailed explanation for the users. Specifically:
- major data corruption issues
- fixes which break backwards compatibility
- fixes which require post-update user action
Bug Fix List
Almost every release includes a list of miscellaneous bug fixes which have accumulated in the last few months. This should be a list of 40% to 70% of the fixes committed to the stable branch. What you include on this list should be significant bugs with user-visible effects, especially things which the originally affected users ought to test. You also often need to condense summary lines for these issues to that they fit on one line. See prior update releases for examples of this.
EOL Notice
We send out at least two notices before EOL'ing a version: one before it's EOL, letting people know that the next update will be the last, and one when it is EOL, letting users know that this is the very last update for that version.
Security Releases
Security releases are ones which contain a fix for one or more security issues sufficient to warrant a CVE.
Because of this security fix information, we cannot use a public process for drafting the release.
Aside from that, most of the process of creating a security release is the same as for creating a regular update release. Below are the parts which are different, otherwise refer to Update Releases above.
Templates
Use the security release template.
Choosing Release Writers
Two weeks before the release, the Release Committee will solicit two writers to work on the release:
- A PR writer from the Advocacy group
- A security expert from the Security group
The PR writer will need to be a community member of proven discretion, but need not be a member of the Security Team.
One to Two Weeks Out
The Security team member will contact the PR Writer with notes about the fixed security releases. The PR Writer will work with the security team member to get those issues summarized succinctly but accurately. This work will be done by email and/or secure, private collaboration mechanisms (but not via git.postgresql.org).
Unlike regular update releases, the PR Writer may not share the full text of the release on pgsql-hackers to look for more information about included patches. Instead, they should share only the patch list, excluding any of the security patches.
Friday before the Release
You may notify RCs that a release is coming, but not its contents.
Three Days Out (Monday)
At this point the fixes for the security release should be committed to git, and we should have final text for the CVEs:
- The Security Team member will share the CVE numbers and text with the PR Writer
- The PR Writer can finalize text check his draft announcement into git.postgresql.org/press
- The PR Writer will create a patch for the website to update the Security Page
- The PR Writer can share the draft release with the Regional Contacts
The patch for the Security Page should list out all CVEs and their associated information in the existing format. This patch will be submitted to the Web Team for review, as well as to the Security Team member for checking the security information.
Follow-ups
One week after the release, if a version of PostgreSQL is now newly EOL, the PR Writer should create a patch to move all of the security issues associated with the EOL release only to the Security Archive Page.
