src/tools/RELEASE_CHANGES - master - githubmirror/postgres

src/tools/RELEASE_CHANGES
259 строк9 KB
Tom Lane
Remove gen_node_support.pl's ad-hoc ABI stability check.
21 апр 2026, 17:58
21 апр 2026, 17:581cd3cd3
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
	o run src/tools/add_commit_links.pl

* 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

* Create .abi-compliance-history file with initial entry shortly before the .0
  stamp.  The easiest way to do this is to copy it from the previous
  REL_*_STABLE branch, remove all entries, and follow the instructions in the
  file to add the initial reference point for the major version.


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 (see src/common/unicode/README)


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)

* It's also advisable to check that copyright years are up-to-date
  (run src/tools/copyright.pl, commit any changes it finds)

* 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.

* In the newly-made branch, replace "devel" with the branch's major version
  number in the URLs appearing in the top-level README and Makefile files.

* 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