src/tools/RELEASE_CHANGES

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