granicus.if.org Git - postgresql/blob - src/tools/RELEASE_CHANGES

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