src/tools/RELEASE_CHANGES

   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 * Create a branch in git for maintenance of the previous release
  93         o on master branch, do:
  94                 git pull           # be sure you have the latest "master"
  95                 git branch "new-branch-name"
  96                 git push -u origin  "new-branch-name"
  97           for example,
  98                 git branch REL_11_STABLE
  99                 git push -u origin REL_11_STABLE
 100
 101 * Add new branch's name to list in src/tools/git_changelog
 102
 103 * Increment the major version number in src/tools/version_stamp.pl
 104
 105 * Run "src/tools/version_stamp.pl devel", then run autoconf
 106
 107 * Create a new doc/src/sgml/release-NN.sgml file (initially just a
 108   placeholder), "git rm" the previous one, and update release.sgml and
 109   filelist.sgml to match.
 110
 111 * In the newly-made branch, replace "devel" with the branch's major version
 112   number in the URLs appearing in the top-level README and Makefile files.
 113
 114 * In the newly-made branch, change src/backend/nodes/gen_node_support.pl
 115   to enforce ABI stability of the NodeTag list (see "ARM ABI STABILITY
 116   CHECK HERE" therein).
 117
 118 * Notify the private committers email list, to ensure all committers
 119   are aware of the new branch even if they're not paying close attention
 120   to pgsql-hackers.
 121
 122 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
 123   branch.  Once the buildfarm server is accepting reports, notify the
 124   buildfarm owners' email list, for the benefit of owners who use manual
 125   branch scheduling.
 126
 127
 128 Creating Back-Branch Release Notes
 129 ==================================
 130
 131 * Run src/tools/git_changelog to generate a list of relevant commits.
 132   You can also run 'git log' in each branch.  Be sure to use the --since
 133   branch tag and not the release date, as commits could have been done
 134   between branch stamping and the release date.
 135
 136 * Remember to include any older branch commits not in the newest branch.
 137   This can be accomplished by diff'ing the newest and older branch commit
 138   logs and looking for lines that only appear in the older branch, e.g.:
 139
 140        diff commit-N.N.log commit-O.O.log | grep '^>'
 141
 142 * On the most recent release branch (*not* in master), edit and create SGML
 143   markup for relevant changes in that branch's release-NN.sgml file.
 144   Minor release notes should include more small change details because
 145   testing is limited.
 146
 147 * Copy this text into older branches' release-NN.sgml files, then remove
 148   items that do not apply based on commit logs for that branch.
 149
 150 * The minor release notes for the oldest active branch should always
 151   include a warning about its impending EOL.  Use the same boilerplate
 152   text used in previous branches.
 153
 154
 155 Retiring a Branch
 156 =================
 157
 158 * Notify the private committers email list, to ensure all committers
 159   are aware of the branch being dead.
 160
 161 * Get the buildfarm's 'branches_of_interest.txt' file updated to remove
 162   the retired branch.  Then notify the buildfarm owners' email list,
 163   for the benefit of owners who use manual branch scheduling.
 164
 165
 166
 167 ---------------------------------------------------------------------------
 168
 169                        Library Version Changes
 170                        =======================
 171
 172 Major Version
 173 =============
 174
 175 The major version number should be updated whenever the source of the
 176 library changes to make it binary incompatible. Such changes include,
 177 but are not limited to:
 178
 179 1. Removing a public function or structure (or typedef, enum, ...)
 180
 181 2. Modifying a public functions arguments.
 182
 183 3. Removing a field from a public structure.
 184
 185 4. Adding a field to a public structure, unless steps have been
 186 previously taken to shield users from such a change, for example by
 187 such structures only ever being allocated/instantiated by a library
 188 function which would give the new field a suitable default value.
 189
 190 Adding a new function should NOT force an increase in the major version
 191 number. (Packagers will see the standard minor number update and install
 192 the new library.)  When the major version is increased all applications
 193 which link to the library MUST be recompiled - this is not desirable.
 194
 195 Minor Version
 196 =============
 197
 198 The minor version number should be updated whenever the functionality of
 199 the library has changed, typically a change in source code between releases
 200 would mean an increase in the minor version number so long as it does not
 201 require a major version increase.
 202
 203 Given that we make at least some changes to our libraries in every major
 204 PostgreSQL version, we always bump all minor library version numbers in
 205 each development cycle as a matter of policy.  This is currently mechanized
 206 by referencing the MAJORVERSION make macro in the value of SO_MINOR_VERSION
 207 for each shared library.  As of v10, SO_MINOR_VERSION is simply equal to
 208 MAJORVERSION in all cases.  If we ever make an incompatible break in a
 209 library's API, forcing a major version bump, we could continue to increase
 210 SO_MINOR_VERSION (thus, perhaps, going from libpq.so.5.12 to libpq.so.6.13),
 211 or we could reset SO_MINOR_VERSION to zero, using makefile code along the
 212 lines of
 213         SO_MINOR_VERSION= $(shell expr $(MAJORVERSION) - 13)
 214 so that the number continues to increase automatically in later branches.
 215 For now, that complication is not necessary.
 216
 217 Minimizing Changes
 218 ==================
 219
 220 When modifying public functions arguments, steps should be taken to
 221 maintain binary compatibility across minor PostgreSQL releases (e.g. the
 222 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
 223 function:
 224
 225         void print_stuff(int arg1, int arg2)
 226         {
 227             printf("stuff: %d %d\n", arg1, arg2);
 228         }
 229
 230 If we wanted to add a third argument:
 231
 232         void print_stuff(int arg1, int arg2, int arg3)
 233         {
 234             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 235         }
 236
 237 Then doing it like this:
 238
 239         void print_stuff2(int arg1, int arg2, int arg3)
 240         {
 241             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 242         }
 243
 244         void print_stuff(int arg1, int arg2)
 245         {
 246             print_stuff2(arg1, arg2, 0);
 247         }
 248
 249 would maintain binary compatibility. Obviously this would add a fair
 250 bit of cruft if used extensively, but considering the changes between
 251 minor versions would probably be worthwhile to avoid bumping library
 252 major version. Naturally in the next major version print_stuff() would
 253 assume the functionality and arguments of print_stuff2().
 254
 255
 256 Lee Kindness