1 For All Releases (major, minor, beta, RC)
4 * Release version number changes
5 o run src/tools/version_stamp.pl, then run autoconf
9 o run git log and, if useful, src/tools/git_changelog
10 o update doc/src/sgml/release-NN.sgml in relevant branches
11 o run spellchecker on result
14 * Update timezone data to match latest IANA timezone database and new
15 Windows releases, if any (see src/timezone/README)
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.
31 (in addition to the above)
33 Note that once the release branch has been forked off in git,
34 release-note editing happens in that branch, not in master.
35 Updates to the rest of the documentation usually need to happen
36 in both master and the branch.
39 o use src/tools/git_changelog
40 o retain the relevant commits
41 o new features and options
42 o major performance improvements
43 o bug fixes for serious or common bugs
44 o incompatibilities and significant user-visible changes
45 o major source code changes
46 o update TODO list, http://wiki.postgresql.org/wiki/Todo
47 o verify items marked as completed are completed
48 o mark additional items as completed
49 o remove completed items
50 o group items into categories
51 o select incompatibilities
52 o add documentation links for items
53 o select major features
56 o document all new features
57 o update help output from inside the programs
58 o doc/src/sgml/ref manual pages
61 o update ports list in doc/src/sgml/installation.sgml
62 o update platform-specific FAQ's, if needed
68 These things should be done at least once per development cycle.
69 Typically we do them between feature freeze and start of beta test,
70 but there may be reasons to do them at other times as well.
72 * Renumber any manually-assigned OIDs between 8000 and 9999
73 to lower numbers, using renumber_oids.pl (see notes in bki.sgml)
75 * Update config.guess and config.sub
76 (from http://savannah.gnu.org/projects/config)
78 * Update inet/cidr data types with newest Bind patches
80 * Update Unicode data: Edit UNICODE_VERSION and CLDR_VERSION in
81 src/Makefile.global.in, run make update-unicode, and commit.
84 Starting a New Development Cycle
85 ================================
87 * Typically, we do pgindent and perltidy runs just before branching
89 * Create a branch in git for maintenance of the previous release
90 o on master branch, do:
91 git pull # be sure you have the latest "master"
92 git branch "new-branch-name"
93 git push -u origin "new-branch-name"
95 git branch REL_11_STABLE
96 git push -u origin REL_11_STABLE
98 * Add new branch's name to list in src/tools/git_changelog
100 * Increment the major version number in src/tools/version_stamp.pl
102 * Run "src/tools/version_stamp.pl devel", then run autoconf
104 * Create a new doc/src/sgml/release-NN.sgml file (initially just a
105 placeholder), "git rm" the previous one, and update release.sgml and
106 filelist.sgml to match.
108 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
112 Creating Back-Branch Release Notes
113 ==================================
115 * Run src/tools/git_changelog to generate a list of relevant commits.
116 You can also run 'git log' in each branch. Be sure to use the --since
117 branch tag and not the release date, as commits could have been done
118 between branch stamping and the release date.
120 * Remember to include any older branch commits not in the newest branch.
121 This can be accomplished by diff'ing the newest and older branch commit
122 logs and looking for lines that only appear in the older branch, e.g.:
124 diff commit-N.N.log commit-O.O.log | grep '^>'
126 * On the most recent release branch (*not* in master), edit and create SGML
127 markup for relevant changes in that branch's release-NN.sgml file.
128 Minor release notes should include more small change details because
131 * Copy this text into older branches' release-NN.sgml files, then remove
132 items that do not apply based on commit logs for that branch.
134 * The minor release notes for the oldest active branch should always
135 include a warning about its impending EOL. Use the same boilerplate
136 text used in previous branches.
142 * Get the buildfarm's 'branches_of_interest.txt' file updated to remove
147 ---------------------------------------------------------------------------
149 Library Version Changes
150 =======================
155 The major version number should be updated whenever the source of the
156 library changes to make it binary incompatible. Such changes include,
157 but are not limited to:
159 1. Removing a public function or structure (or typedef, enum, ...)
161 2. Modifying a public functions arguments.
163 3. Removing a field from a public structure.
165 4. Adding a field to a public structure, unless steps have been
166 previously taken to shield users from such a change, for example by
167 such structures only ever being allocated/instantiated by a library
168 function which would give the new field a suitable default value.
170 Adding a new function should NOT force an increase in the major version
171 number. (Packagers will see the standard minor number update and install
172 the new library.) When the major version is increased all applications
173 which link to the library MUST be recompiled - this is not desirable.
178 The minor version number should be updated whenever the functionality of
179 the library has changed, typically a change in source code between releases
180 would mean an increase in the minor version number so long as it does not
181 require a major version increase.
183 Given that we make at least some changes to our libraries in every major
184 PostgreSQL version, we always bump all minor library version numbers in
185 each development cycle as a matter of policy. This is currently mechanized
186 by referencing the MAJORVERSION make macro in the value of SO_MINOR_VERSION
187 for each shared library. As of v10, SO_MINOR_VERSION is simply equal to
188 MAJORVERSION in all cases. If we ever make an incompatible break in a
189 library's API, forcing a major version bump, we could continue to increase
190 SO_MINOR_VERSION (thus, perhaps, going from libpq.so.5.12 to libpq.so.6.13),
191 or we could reset SO_MINOR_VERSION to zero, using makefile code along the
193 SO_MINOR_VERSION= $(shell expr $(MAJORVERSION) - 13)
194 so that the number continues to increase automatically in later branches.
195 For now, that complication is not necessary.
200 When modifying public functions arguments, steps should be taken to
201 maintain binary compatibility across minor PostgreSQL releases (e.g. the
202 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
205 void print_stuff(int arg1, int arg2)
207 printf("stuff: %d %d\n", arg1, arg2);
210 If we wanted to add a third argument:
212 void print_stuff(int arg1, int arg2, int arg3)
214 printf("stuff: %d %d %d\n", arg1, arg2, arg3);
217 Then doing it like this:
219 void print_stuff2(int arg1, int arg2, int arg3)
221 printf("stuff: %d %d %d\n", arg1, arg2, arg3);
224 void print_stuff(int arg1, int arg2)
226 print_stuff2(arg1, arg2, 0);
229 would maintain binary compatibility. Obviously this would add a fair
230 bit of cruft if used extensively, but considering the changes between
231 minor versions would probably be worthwhile to avoid bumping library
232 major version. Naturally in the next major version print_stuff() would
233 assume the functionality and arguments of print_stuff2().