src/tools/RELEASE_CHANGES - cloudberry - Git at Google

 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"
   (see src/tools/pgindent/README)

 * Update .git-blame-ignore-revs. It should contain all of the newly
   created code beautification commits.  Make sure that you use
   full-length commit hashes for this.

 * 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

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

 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
   branch.


 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
 =================

 * Get the buildfarm's 'branches_of_interest.txt' file updated to remove
   the retired branch.


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

                        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
	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"
	(see src/tools/pgindent/README)

	* Update .git-blame-ignore-revs. It should contain all of the newly
	created code beautification commits. Make sure that you use
	full-length commit hashes for this.

	* 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

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

	* Get the buildfarm's 'branches_of_interest.txt' file updated with the new
	branch.


	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
	=================

	* Get the buildfarm's 'branches_of_interest.txt' file updated to remove
	the retired branch.



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

	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