1For All Releases (major, minor, beta, RC) 2================ 3 4* Release version number changes 5 o run src/tools/version_stamp.pl, then run autoconf 6 (by packager) (beta) 7 8* Release notes 9 o run git log and, if useful, src/tools/git_changelog 10 o update doc/src/sgml/release.sgml 11 o run spellchecker on result 12 o add SGML markup 13 14* Update timezone data to match latest IANA timezone database and new 15 Windows releases, if any (see src/timezone/README) 16 17* Translation updates 18 1. Check out the messages repository (of the right branch) from 19 <http://git.postgresql.org/git/pgtranslation/messages.git>. 20 2. Check out the admin repository from 21 <http://git.postgresql.org/git/pgtranslation/admin.git>. 22 3. From babel.postgresql.org, download the "qualified list" 23 for the respective branch. 24 4. Run ".../admin/cp-po -L qualified-list-xxx.txt -g .../messages .../postgresql". 25 This creates a commit in the postgresql repository. 26 5. Push everything. 27 28 29For Major Releases 30================== 31(in addition to the above) 32 33* Release notes 34 o use src/tools/git_changelog 35 o retain the relevant commits 36 o new features and options 37 o major performance improvements 38 o bug fixes for serious or common bugs 39 o incompatibilities and significant user-visible changes 40 o major source code changes 41 o update TODO list, http://wiki.postgresql.org/wiki/Todo 42 o verify items marked as completed are completed 43 o mark additional items as completed 44 o remove completed items 45 o group items into categories 46 o select incompatibilities 47 o add documentation links for items 48 o select major features 49 50* Documentation 51 o document all new features 52 o update help output from inside the programs 53 o doc/src/sgml/ref manual pages 54 o update the sizes specified for installation requirements 55 (doc/src/sgml/installation.sgml, section "install-requirements") 56 o update the shared memory size requirement table 57 (doc/src/sgml/runtime.sgml, section "shared-memory-parameters") 58 59* Ports 60 o update config.guess and config.sub at the start of beta 61 (from http://savannah.gnu.org/projects/config) 62 o update ports list in doc/src/sgml/installation.sgml 63 o update platform-specific FAQ's, if needed 64 65* Update inet/cidr data types with newest Bind patches 66 67 68Starting a New Development Cycle 69================================ 70 71* Typically, we do pgindent and perltidy runs just before branching 72 73* Create a branch in git for maintenance of the previous release 74 o on master branch, do: 75 git pull # be sure you have the latest "master" 76 git push origin master:refs/heads/"new-branch-name" 77 for example, 78 git push origin master:refs/heads/REL_10_STABLE 79 80* Add new branch's name to list in src/tools/git_changelog 81 82* Increment the major version number in src/tools/version_stamp.pl 83 84* Run "src/tools/version_stamp.pl devel", then run autoconf 85 86 87Creating Back-Branch Release Notes 88================================== 89 90* Run src/tools/git_changelog to generate a list of relevant commits. 91 You can also run 'git log' in each branch. Be sure to use the --since 92 branch tag and not the release date, as commits could have been done 93 between branch stamping and the release date. 94 95* On the git master branch, edit and create SGML markup for the most recent 96 branch in that branch's release-N.N.sgml file. Minor release notes 97 should include more small change details because testing is limited. 98 99* Copy this into older branches' release-N.N.sgml files, then remove 100 items that do not apply based on commit logs for that branch. 101 102* Add any older branch commits not in the newest branch. This can be 103 accomplished by diff'ing the newest and older branch commit logs and 104 looking for lines that only appear in the older branch, e.g.: 105 106 diff commit-N.N.log commit-O.O.log | grep '^>' 107 108* Copy the appropriate release-N.N.sgml files into each back branch SGML 109 directory. 110 111 112 113--------------------------------------------------------------------------- 114 115 Library Version Changes 116 ======================= 117 118Major Version 119============= 120 121The major version number should be updated whenever the source of the 122library changes to make it binary incompatible. Such changes include, 123but are not limited to: 124 1251. Removing a public function or structure (or typedef, enum, ...) 126 1272. Modifying a public functions arguments. 128 1293. Removing a field from a public structure. 130 1314. Adding a field to a public structure, unless steps have been 132previously taken to shield users from such a change, for example by 133such structures only ever being allocated/instantiated by a library 134function which would give the new field a suitable default value. 135 136Adding a new function should NOT force an increase in the major version 137number. (Packagers will see the standard minor number update and install 138the new library.) When the major version is increased all applications 139which link to the library MUST be recompiled - this is not desirable. 140 141Minor Version 142============= 143 144The minor version number should be updated whenever the functionality of 145the library has changed, typically a change in source code between releases 146would mean an increase in the minor version number so long as it does not 147require a major version increase. 148 149Given that we make at least some changes to our libraries in every major 150PostgreSQL version, we always bump all minor library version numbers in 151each development cycle as a matter of policy. This is currently mechanized 152by referencing the MAJORVERSION make macro in the value of SO_MINOR_VERSION 153for each shared library. As of v10, SO_MINOR_VERSION is simply equal to 154MAJORVERSION in all cases. If we ever make an incompatible break in a 155library's API, forcing a major version bump, we could continue to increase 156SO_MINOR_VERSION (thus, perhaps, going from libpq.so.5.12 to libpq.so.6.13), 157or we could reset SO_MINOR_VERSION to zero, using makefile code along the 158lines of 159 SO_MINOR_VERSION= $(shell expr $(MAJORVERSION) - 13) 160so that the number continues to increase automatically in later branches. 161For now, that complication is not necessary. 162 163Minimizing Changes 164================== 165 166When modifying public functions arguments, steps should be taken to 167maintain binary compatibility across minor PostgreSQL releases (e.g. the 1687.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following 169function: 170 171 void print_stuff(int arg1, int arg2) 172 { 173 printf("stuff: %d %d\n", arg1, arg2); 174 } 175 176If we wanted to add a third argument: 177 178 void print_stuff(int arg1, int arg2, int arg3) 179 { 180 printf("stuff: %d %d %d\n", arg1, arg2, arg3); 181 } 182 183Then doing it like this: 184 185 void print_stuff2(int arg1, int arg2, int arg3) 186 { 187 printf("stuff: %d %d %d\n", arg1, arg2, arg3); 188 } 189 190 void print_stuff(int arg1, int arg2) 191 { 192 print_stuff2(arg1, arg2, 0); 193 } 194 195would maintain binary compatibility. Obviously this would add a fair 196bit of cruft if used extensively, but considering the changes between 197minor versions would probably be worthwhile to avoid bumping library 198major version. Naturally in the next major version print_stuff() would 199assume the functionality and arguments of print_stuff2(). 200 201 202Lee Kindness 203