For All Releases (major, minor, beta, RC) ================ * Release version number changes o run src/tools/version_stamp.pl, then run autoconf (by packager) (beta) * Release notes o run git log and, if useful, src/tools/git_changelog o update doc/src/sgml/release-NN.sgml in relevant branches o run spellchecker on result o add SGML markup * Update timezone data to match latest IANA timezone database and new Windows releases, if any (see src/timezone/README) * Translation updates 1. Check out the messages repository (of the right branch) from . 2. Check out the admin repository from . 3. From babel.postgresql.org, download the "qualified list" for the respective branch. 4. Run ".../admin/cp-po -L qualified-list-xxx.txt -g .../messages .../postgresql". This creates a commit in the postgresql repository. 5. Push everything. For Major Releases ================== (in addition to the above) Note that once the release branch has been forked off in git, release-note editing happens in that branch, not in master. Updates to the rest of the documentation usually need to happen in both master and the branch. * Release notes o use src/tools/git_changelog o retain the relevant commits o new features and options o major performance improvements o bug fixes for serious or common bugs o incompatibilities and significant user-visible changes o major source code changes o update TODO list, http://wiki.postgresql.org/wiki/Todo o verify items marked as completed are completed o mark additional items as completed o remove completed items o group items into categories o select incompatibilities o add documentation links for items o select major features * Documentation o document all new features o update help output from inside the programs o doc/src/sgml/ref manual pages * Ports o update ports list in doc/src/sgml/installation.sgml Pre-Beta Tasks ============== These things should be done at least once per development cycle. Typically we do them between feature freeze and start of beta test, but there may be reasons to do them at other times as well. * Run mechanical code beautification tools: pgindent, pgperltidy, and "make reformat-dat-files" (complete steps from src/tools/pgindent/README) * Renumber any manually-assigned OIDs between 8000 and 9999 to lower numbers, using renumber_oids.pl (see notes in bki.sgml) * Update config.guess and config.sub (from https://savannah.gnu.org/projects/config) * Update Unicode data: Edit UNICODE_VERSION and CLDR_VERSION in src/Makefile.global.in, run make update-unicode, and commit. Starting a New Development Cycle ================================ * Typically, we do pgindent and perltidy runs just before branching, as well as before beta (complete steps from src/tools/pgindent/README) * Create a branch in git for maintenance of the previous release o on master branch, do: git pull # be sure you have the latest "master" git branch "new-branch-name" git push -u origin "new-branch-name" for example, git branch REL_11_STABLE git push -u origin REL_11_STABLE * Add new branch's name to list in src/tools/git_changelog * Increment the major version number in src/tools/version_stamp.pl * Run "src/tools/version_stamp.pl devel", then run autoconf * Create a new doc/src/sgml/release-NN.sgml file (initially just a placeholder), "git rm" the previous one, and update release.sgml and filelist.sgml to match. * Notify the private committers email list, to ensure all committers are aware of the new branch even if they're not paying close attention to pgsql-hackers. * Get the buildfarm's 'branches_of_interest.txt' file updated with the new branch. Once the buildfarm server is accepting reports, notify the buildfarm owners' email list, for the benefit of owners who use manual branch scheduling. Creating Back-Branch Release Notes ================================== * Run src/tools/git_changelog to generate a list of relevant commits. You can also run 'git log' in each branch. Be sure to use the --since branch tag and not the release date, as commits could have been done between branch stamping and the release date. * Remember to include any older branch commits not in the newest branch. This can be accomplished by diff'ing the newest and older branch commit logs and looking for lines that only appear in the older branch, e.g.: diff commit-N.N.log commit-O.O.log | grep '^>' * On the most recent release branch (*not* in master), edit and create SGML markup for relevant changes in that branch's release-NN.sgml file. Minor release notes should include more small change details because testing is limited. * Copy this text into older branches' release-NN.sgml files, then remove items that do not apply based on commit logs for that branch. * The minor release notes for the oldest active branch should always include a warning about its impending EOL. Use the same boilerplate text used in previous branches. Retiring a Branch ================= * Notify the private committers email list, to ensure all committers are aware of the branch being dead. * Get the buildfarm's 'branches_of_interest.txt' file updated to remove the retired branch. Then notify the buildfarm owners' email list, for the benefit of owners who use manual branch scheduling. --------------------------------------------------------------------------- Library Version Changes ======================= Major Version ============= The major version number should be updated whenever the source of the library changes to make it binary incompatible. Such changes include, but are not limited to: 1. Removing a public function or structure (or typedef, enum, ...) 2. Modifying a public functions arguments. 3. Removing a field from a public structure. 4. Adding a field to a public structure, unless steps have been previously taken to shield users from such a change, for example by such structures only ever being allocated/instantiated by a library function which would give the new field a suitable default value. Adding a new function should NOT force an increase in the major version number. (Packagers will see the standard minor number update and install the new library.) When the major version is increased all applications which link to the library MUST be recompiled - this is not desirable. Minor Version ============= The minor version number should be updated whenever the functionality of the library has changed, typically a change in source code between releases would mean an increase in the minor version number so long as it does not require a major version increase. Given that we make at least some changes to our libraries in every major PostgreSQL version, we always bump all minor library version numbers in each development cycle as a matter of policy. This is currently mechanized by referencing the MAJORVERSION make macro in the value of SO_MINOR_VERSION for each shared library. As of v10, SO_MINOR_VERSION is simply equal to MAJORVERSION in all cases. If we ever make an incompatible break in a library's API, forcing a major version bump, we could continue to increase SO_MINOR_VERSION (thus, perhaps, going from libpq.so.5.12 to libpq.so.6.13), or we could reset SO_MINOR_VERSION to zero, using makefile code along the lines of SO_MINOR_VERSION= $(shell expr $(MAJORVERSION) - 13) so that the number continues to increase automatically in later branches. For now, that complication is not necessary. Minimizing Changes ================== When modifying public functions arguments, steps should be taken to maintain binary compatibility across minor PostgreSQL releases (e.g. the 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following function: void print_stuff(int arg1, int arg2) { printf("stuff: %d %d\n", arg1, arg2); } If we wanted to add a third argument: void print_stuff(int arg1, int arg2, int arg3) { printf("stuff: %d %d %d\n", arg1, arg2, arg3); } Then doing it like this: void print_stuff2(int arg1, int arg2, int arg3) { printf("stuff: %d %d %d\n", arg1, arg2, arg3); } void print_stuff(int arg1, int arg2) { print_stuff2(arg1, arg2, 0); } would maintain binary compatibility. Obviously this would add a fair bit of cruft if used extensively, but considering the changes between minor versions would probably be worthwhile to avoid bumping library major version. Naturally in the next major version print_stuff() would assume the functionality and arguments of print_stuff2(). Lee Kindness