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 scan cvs logs, use pgcvslog and flags in comments
  10         o update doc/src/sgml/release.sgml
  11         o run spellchecker on result
  12         o add SGML markup
  13         o check if 'gmake HISTORY.html' works for <link>s
  14
  15 * Update timezone data to match latest zic database (see src/timezone/README)
  16
  17 * Translation updates
  18         Translations are kept in the project "pgtranslation" on PgFoundry.
  19         1. Check out the messages module (of the right branch).
  20         2. Check out the admin module.
  21         3. Run "sh .../admin/cp-po .../messages .../pgsql
  22         4. Commit.
  23
  24
  25 For Major Releases
  26 ==================
  27 (in addition to the above)
  28
  29 * Bump minor library versions, major if appropriate (see below)
  30         o src/interfaces/*/Makefile
  31         o src/interfaces/*/*/Makefile
  32
  33 * Release notes
  34         o check completion of items that have been marked as completed at
  35           http://wiki.postgresql.org/wiki/Todo
  36         o remove completed TODO items
  37         o group items into categories
  38         o select major features
  39         o select incompatibilities
  40         o add documentation for items
  41
  42 * Documentation
  43         o document all new features
  44         o update help output from inside the programs
  45         o doc/src/sgml/ref manual pages
  46         o convert any literal "<" and ">" characters, use tools/find_gt_lt
  47
  48 * Ports
  49         o update config.guess and config.sub at the start of beta
  50           (from http://savannah.gnu.org/projects/config)
  51         o update ports list in doc/src/sgml/installation.sgml
  52         o update platform-specific FAQ's, if needed
  53
  54 * Update inet/cidr data types with newest Bind patches
  55
  56
  57 Starting a New Development Cycle
  58 ================================
  59
  60 * Create a branch in CVS for maintenance of the previous release
  61
  62 * Increment the major version number in src/tools/version_stamp.pl
  63
  64 * Run "src/tools/version_stamp.pl devel", then run autoconf
  65
  66
  67 Creating Back-Branch Release Notes
  68 ==================================
  69
  70 * Do 'cvs log' on each back-branch and run pgcvslog
  71
  72 * In CVS HEAD, edit and create SGML markup for the most recent branch
  73   in that branch's release-N.N.sgml file
  74
  75 * Copy this into older branches' release-N.N.sgml files, then remove
  76   items that do not apply based on cvs logs for that branch (and add
  77   any that are needed)
  78
  79 * Copy the appropriate release-N.N.sgml files into each back CVS branch
  80
  81
  82 ---------------------------------------------------------------------------
  83
  84                        Library Version Changes
  85                        =======================
  86
  87 Major Version
  88 =============
  89
  90 The major version number should be updated whenever the source of the
  91 library changes to make it binary incompatible. Such changes include,
  92 but are not limited to:
  93
  94 1. Removing a public function or structure (or typedef, enum, ...)
  95
  96 2. Modifying a public functions arguments.
  97
  98 3. Removing a field from a public structure.
  99
 100 4. Adding a field to a public structure, unless steps have been
 101 previously taken to shield users from such a change, for example by
 102 such structures only ever being allocated/instantiated by a library
 103 function which would give the new field a suitable default value.
 104
 105 Adding a new function should NOT force an increase in the major version
 106 number. (Packagers will see the standard minor number update and install
 107 the new library.)  When the major version is increased all applications
 108 which link to the library MUST be recompiled - this is not desirable. When
 109 the major version is updated the minor version gets reset.
 110
 111 Minor Version
 112 =============
 113
 114 The minor version number should be updated whenever the functionality of
 115 the library has changed, typically a change in source code between releases
 116 would mean an increase in the minor version number so long as it does not
 117 require a major version increase.
 118
 119 Given that we make at least minor changes to our libraries in every major
 120 PostgreSQL version, we always bump all minor library version numbers at the
 121 start of each development cycle as a matter of policy.
 122
 123 Minimizing Changes
 124 ==================
 125
 126 When modifying public functions arguments, steps should be taken to
 127 maintain binary compatibility across minor PostgreSQL releases (e.g. the
 128 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
 129 function:
 130
 131         void print_stuff(int arg1, int arg2)
 132         {
 133             printf("stuff: %d %d\n", arg1, arg2);
 134         }
 135
 136 If we wanted to add a third argument:
 137
 138         void print_stuff(int arg1, int arg2, int arg3)
 139         {
 140             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 141         }
 142
 143 Then doing it like this:
 144
 145         void print_stuff2(int arg1, int arg2, int arg3)
 146         {
 147             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 148         }
 149
 150         void print_stuff(int arg1, int arg2)
 151         {
 152             print_stuff(arg1, arg2, 0);
 153         }
 154
 155 would maintain binary compatibility. Obviously this would add a fair
 156 bit of cruft if used extensively, but considering the changes between
 157 minor versions would probably be worthwhile to avoid bumping library
 158 major version. Naturally in the next major version print_stuff() would
 159 assume the functionality and arguments of print_stuff2().
 160
 161
 162 Lee Kindness