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