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         o update platform-specific FAQ's, if needed
  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 * Renumber any manually-assigned OIDs between 8000 and 9999
  73   to lower numbers, using renumber_oids.pl (see notes in bki.sgml)
  74
  75 * Update config.guess and config.sub
  76   (from http://savannah.gnu.org/projects/config)
  77
  78 * Update inet/cidr data types with newest Bind patches
  79
  80 * Update Unicode data: Edit UNICODE_VERSION and CLDR_VERSION in
  81   src/Makefile.global.in, run make update-unicode, and commit.
  82
  83
  84 Starting a New Development Cycle
  85 ================================
  86
  87 * Typically, we do pgindent and perltidy runs just before branching
  88
  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"
  94           for example,
  95                 git branch REL_11_STABLE
  96                 git push -u origin REL_11_STABLE
  97
  98 * Add new branch's name to list in src/tools/git_changelog
  99
 100 * Increment the major version number in src/tools/version_stamp.pl
 101
 102 * Run "src/tools/version_stamp.pl devel", then run autoconf
 103
 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.
 107
 108 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
 109   branch.
 110
 111
 112 Creating Back-Branch Release Notes
 113 ==================================
 114
 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.
 119
 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.:
 123
 124        diff commit-N.N.log commit-O.O.log | grep '^>'
 125
 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
 129   testing is limited.
 130
 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.
 133
 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.
 137
 138
 139 Retiring a Branch
 140 =================
 141
 142 * Get the buildfarm's 'branches_of_interest.txt' file updated to remove
 143   the retired branch.
 144
 145
 146
 147 ---------------------------------------------------------------------------
 148
 149                        Library Version Changes
 150                        =======================
 151
 152 Major Version
 153 =============
 154
 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:
 158
 159 1. Removing a public function or structure (or typedef, enum, ...)
 160
 161 2. Modifying a public functions arguments.
 162
 163 3. Removing a field from a public structure.
 164
 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.
 169
 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.
 174
 175 Minor Version
 176 =============
 177
 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.
 182
 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
 192 lines of
 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.
 196
 197 Minimizing Changes
 198 ==================
 199
 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
 203 function:
 204
 205         void print_stuff(int arg1, int arg2)
 206         {
 207             printf("stuff: %d %d\n", arg1, arg2);
 208         }
 209
 210 If we wanted to add a third argument:
 211
 212         void print_stuff(int arg1, int arg2, int arg3)
 213         {
 214             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 215         }
 216
 217 Then doing it like this:
 218
 219         void print_stuff2(int arg1, int arg2, int arg3)
 220         {
 221             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 222         }
 223
 224         void print_stuff(int arg1, int arg2)
 225         {
 226             print_stuff2(arg1, arg2, 0);
 227         }
 228
 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().
 234
 235
 236 Lee Kindness