postgresql/src/tools/RELEASE_CHANGES

For All Releases (major, minor, beta, RC)
================

* Release version number changes
	o doc/bug.template (beta)
	o bump Win32 interface version numbers
		- src/include/pg_config.h.win32 
		  (string and integer versions) (beta)
		- src/interfaces/libpq/libpq.rc.in
		  (pre-8.0 had just libpq.rc)
		- src/port/win32ver.rc
	o update doc/FAQ and doc/src/FAQ/FAQ.html
	o copy FAQs from HEAD to top-most branch
	o configure.in, and run autoconf or update configure 
	  (by packager) (beta)

* Release notes
	o scan cvs logs, use pgcvslog and flags in comments
	o update doc/src/sgml/release.sgml
	o run spellchecker on result
	o add SGML markup
	o check if 'gmake HISTORY.html' works for <link>s

* Update timezone data to match latest zic database (see src/timezone/README)

* Translation updates
	Translations are kept in the project "pgtranslation" on PgFoundry.
	1. Check out the messages module (of the right branch).
	2. Check out the admin module.
	3. Run "sh .../admin/cp-po .../messages .../pgsql
	4. Commit.


For Major Releases
==================
(in addition to the above)

* Bump minor library versions, major if appropriate (see below)
	o src/interfaces/*/Makefile
	o src/interfaces/*/*/Makefile

* Release notes
	o check that dashed items from the TODO list are complete
	o remove dashed TODO items
	o group items into categories
	o select major features
	o select incompatibilities
	o add documenation for items

* Documentation
	o document all new features
	o update help output from inside the programs
	o doc/src/sgml/ref manual pages
	o convert any literal "<" and ">" characters, use tools/find_gt_lt

* Ports
	o update config.guess and config.sub at the start of beta
	o update ports list in doc/src/sgml/installation.sgml
	o update platform-specific FAQ's, if needed

* Update inet/cidr data types with newest Bind patches


Creating Back-Branch Release Notes
==================================

* Do 'cvs log' on each back-branch and run pgcvslog

* Edit and create SGML markup for the most recent branch

* Make copies of the SGML for each branch, then remove items
  that do not apply based on cvs logs for that branch

* Copy the SGML for each branch into release.sgml in CVS HEAD

* Use src/tools/major_release_split to create a release.sgml for
  each branch and copy them to the branch's CVS


---------------------------------------------------------------------------

                       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. When
the major version is updated the minor version gets reset.

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.

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_stuff(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