1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
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"
(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: 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 (complete steps from src/tools/pgindent/README)
* 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.
* 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
|
