Debian Codegraph @

src/tools/RELEASE_CHANGES

raw
1 For 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-NN.sgml in relevant branches
11 o run spellchecker on result
12 o add SGML markup
13 o run src/tools/add_commit_links.pl
14
15 * Update timezone data to match latest IANA timezone database and new
16 Windows releases, if any (see src/timezone/README)
17
18 * Translation updates
19 1. Check out the messages repository (of the right branch) from
20 <http://git.postgresql.org/git/pgtranslation/messages.git>.
21 2. Check out the admin repository from
22 <http://git.postgresql.org/git/pgtranslation/admin.git>.
23 3. From babel.postgresql.org, download the "qualified list"
24 for the respective branch.
25 4. Run ".../admin/cp-po -L qualified-list-xxx.txt -g .../messages .../postgresql".
26 This creates a commit in the postgresql repository.
27 5. Push everything.
28
29
30 For Major Releases
31 ==================
32 (in addition to the above)
33
34 Note that once the release branch has been forked off in git,
35 release-note editing happens in that branch, not in master.
36 Updates to the rest of the documentation usually need to happen
37 in both master and the branch.
38
39 * Release notes
40 o use src/tools/git_changelog
41 o retain the relevant commits
42 o new features and options
43 o major performance improvements
44 o bug fixes for serious or common bugs
45 o incompatibilities and significant user-visible changes
46 o major source code changes
47 o update TODO list, http://wiki.postgresql.org/wiki/Todo
48 o verify items marked as completed are completed
49 o mark additional items as completed
50 o remove completed items
51 o group items into categories
52 o select incompatibilities
53 o add documentation links for items
54 o select major features
55
56 * Documentation
57 o document all new features
58 o update help output from inside the programs
59 o doc/src/sgml/ref manual pages
60
61 * Ports
62 o update ports list in doc/src/sgml/installation.sgml
63
64
65 Pre-Beta Tasks
66 ==============
67
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.
71
72 * Run mechanical code beautification tools:
73 pgindent, pgperltidy, and "make reformat-dat-files"
74 (complete steps from src/tools/pgindent/README)
75
76 * Renumber any manually-assigned OIDs between 8000 and 9999
77 to lower numbers, using renumber_oids.pl (see notes in bki.sgml)
78
79 * Update config.guess and config.sub
80 (from https://savannah.gnu.org/projects/config)
81
82 * Update Unicode data: Edit UNICODE_VERSION and CLDR_VERSION in
83 src/Makefile.global.in, run make update-unicode, and commit.
84
85
86 Starting a New Development Cycle
87 ================================
88
89 * Typically, we do pgindent and perltidy runs just before branching,
90 as well as before beta (complete steps from src/tools/pgindent/README)
91
92 * It's also advisable to check that copyright years are up-to-date
93 (run src/tools/copyright.pl, commit any changes it finds)
94
95 * Create a branch in git for maintenance of the previous release
96 o on master branch, do:
97 git pull # be sure you have the latest "master"
98 git branch "new-branch-name"
99 git push -u origin "new-branch-name"
100 for example,
101 git branch REL_11_STABLE
102 git push -u origin REL_11_STABLE
103
104 * Add new branch's name to list in src/tools/git_changelog
105
106 * Increment the major version number in src/tools/version_stamp.pl
107
108 * Run "src/tools/version_stamp.pl devel", then run autoconf
109
110 * Create a new doc/src/sgml/release-NN.sgml file (initially just a
111 placeholder), "git rm" the previous one, and update release.sgml and
112 filelist.sgml to match.
113
114 * In the newly-made branch, replace "devel" with the branch's major version
115 number in the URLs appearing in the top-level README and Makefile files.
116
117 * In the newly-made branch, change src/backend/nodes/gen_node_support.pl
118 to enforce ABI stability of the NodeTag list (see "ARM ABI STABILITY
119 CHECK HERE" therein).
120
121 * Notify the private committers email list, to ensure all committers
122 are aware of the new branch even if they're not paying close attention
123 to pgsql-hackers.
124
125 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
126 branch. Once the buildfarm server is accepting reports, notify the
127 buildfarm owners' email list, for the benefit of owners who use manual
128 branch scheduling.
129
130
131 Creating Back-Branch Release Notes
132 ==================================
133
134 * Run src/tools/git_changelog to generate a list of relevant commits.
135 You can also run 'git log' in each branch. Be sure to use the --since
136 branch tag and not the release date, as commits could have been done
137 between branch stamping and the release date.
138
139 * Remember to include any older branch commits not in the newest branch.
140 This can be accomplished by diff'ing the newest and older branch commit
141 logs and looking for lines that only appear in the older branch, e.g.:
142
143 diff commit-N.N.log commit-O.O.log | grep '^>'
144
145 * On the most recent release branch (*not* in master), edit and create SGML
146 markup for relevant changes in that branch's release-NN.sgml file.
147 Minor release notes should include more small change details because
148 testing is limited.
149
150 * Copy this text into older branches' release-NN.sgml files, then remove
151 items that do not apply based on commit logs for that branch.
152
153 * The minor release notes for the oldest active branch should always
154 include a warning about its impending EOL. Use the same boilerplate
155 text used in previous branches.
156
157
158 Retiring a Branch
159 =================
160
161 * Notify the private committers email list, to ensure all committers
162 are aware of the branch being dead.
163
164 * Get the buildfarm's 'branches_of_interest.txt' file updated to remove
165 the retired branch. Then notify the buildfarm owners' email list,
166 for the benefit of owners who use manual branch scheduling.
167
168
169
170 ---------------------------------------------------------------------------
171
172 Library Version Changes
173 =======================
174
175 Major Version
176 =============
177
178 The major version number should be updated whenever the source of the
179 library changes to make it binary incompatible. Such changes include,
180 but are not limited to:
181
182 1. Removing a public function or structure (or typedef, enum, ...)
183
184 2. Modifying a public functions arguments.
185
186 3. Removing a field from a public structure.
187
188 4. Adding a field to a public structure, unless steps have been
189 previously taken to shield users from such a change, for example by
190 such structures only ever being allocated/instantiated by a library
191 function which would give the new field a suitable default value.
192
193 Adding a new function should NOT force an increase in the major version
194 number. (Packagers will see the standard minor number update and install
195 the new library.) When the major version is increased all applications
196 which link to the library MUST be recompiled - this is not desirable.
197
198 Minor Version
199 =============
200
201 The minor version number should be updated whenever the functionality of
202 the library has changed, typically a change in source code between releases
203 would mean an increase in the minor version number so long as it does not
204 require a major version increase.
205
206 Given that we make at least some changes to our libraries in every major
207 PostgreSQL version, we always bump all minor library version numbers in
208 each development cycle as a matter of policy. This is currently mechanized
209 by referencing the MAJORVERSION make macro in the value of SO_MINOR_VERSION
210 for each shared library. As of v10, SO_MINOR_VERSION is simply equal to
211 MAJORVERSION in all cases. If we ever make an incompatible break in a
212 library's API, forcing a major version bump, we could continue to increase
213 SO_MINOR_VERSION (thus, perhaps, going from libpq.so.5.12 to libpq.so.6.13),
214 or we could reset SO_MINOR_VERSION to zero, using makefile code along the
215 lines of
216 SO_MINOR_VERSION= $(shell expr $(MAJORVERSION) - 13)
217 so that the number continues to increase automatically in later branches.
218 For now, that complication is not necessary.
219
220 Minimizing Changes
221 ==================
222
223 When modifying public functions arguments, steps should be taken to
224 maintain binary compatibility across minor PostgreSQL releases (e.g. the
225 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
226 function:
227
228 void print_stuff(int arg1, int arg2)
229 {
230 printf("stuff: %d %d\n", arg1, arg2);
231 }
232
233 If we wanted to add a third argument:
234
235 void print_stuff(int arg1, int arg2, int arg3)
236 {
237 printf("stuff: %d %d %d\n", arg1, arg2, arg3);
238 }
239
240 Then doing it like this:
241
242 void print_stuff2(int arg1, int arg2, int arg3)
243 {
244 printf("stuff: %d %d %d\n", arg1, arg2, arg3);
245 }
246
247 void print_stuff(int arg1, int arg2)
248 {
249 print_stuff2(arg1, arg2, 0);
250 }
251
252 would maintain binary compatibility. Obviously this would add a fair
253 bit of cruft if used extensively, but considering the changes between
254 minor versions would probably be worthwhile to avoid bumping library
255 major version. Naturally in the next major version print_stuff() would
256 assume the functionality and arguments of print_stuff2().
257
258
259 Lee Kindness