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