diff options
Diffstat (limited to 'src/tools/RELEASE_CHANGES')
-rw-r--r-- | src/tools/RELEASE_CHANGES | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES new file mode 100644 index 0000000..e8de724 --- /dev/null +++ b/src/tools/RELEASE_CHANGES @@ -0,0 +1,248 @@ +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 + <http://git.postgresql.org/git/pgtranslation/messages.git>. + 2. Check out the admin repository from + <http://git.postgresql.org/git/pgtranslation/admin.git>. + 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 |