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 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.sgml
  11         o run spellchecker on result
  12         o add SGML markup
  13
  14 * Update timezone data to match latest zic 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. Tag the messages: git tag RELx_y_z
  27         6. Push everything.
  28
  29
  30 For Major Releases
  31 ==================
  32 (in addition to the above)
  33
  34 * Release notes
  35         o use git log or src/tools/git_changelog to find the relevant commits
  36         o check completion of items that have been marked as completed at
  37           http://wiki.postgresql.org/wiki/Todo
  38         o remove completed TODO items
  39         o group items into categories
  40         o select major features
  41         o select incompatibilities
  42         o add documentation for items
  43
  44 * Documentation
  45         o document all new features
  46         o update help output from inside the programs
  47         o doc/src/sgml/ref manual pages
  48         o update the sizes specified for installation requirements
  49           (doc/src/sgml/installation.sgml, section "install-requirements")
  50         o update the shared memory size requirement table
  51           (doc/src/sgml/runtime.sgml, section "shared-memory-parameters")
  52
  53 * Ports
  54         o update config.guess and config.sub at the start of beta
  55           (from http://savannah.gnu.org/projects/config)
  56         o update ports list in doc/src/sgml/installation.sgml
  57         o update platform-specific FAQ's, if needed
  58
  59 * Update inet/cidr data types with newest Bind patches
  60
  61
  62 Starting a New Development Cycle
  63 ================================
  64
  65 * Create a branch in git for maintenance of the previous release
  66         o on master branch, do:
  67                 git pull           # be sure you have the latest "master"
  68                 git push origin master:refs/heads/"new-branch-name"
  69           for example,
  70                 git push origin master:refs/heads/REL9_2_STABLE
  71
  72 * Increment the major version number in src/tools/version_stamp.pl
  73
  74 * Run "src/tools/version_stamp.pl devel", then run autoconf
  75
  76 * Add version tag to src/tools/git_changelog
  77
  78 * Bump minor library versions, major if appropriate (see below)
  79   o Look for SO_MINOR_VERSION and MINOR_VERSION macros in
  80         src/interfaces/ecpg/compatlib/Makefile
  81         src/interfaces/ecpg/ecpglib/Makefile
  82         src/interfaces/ecpg/pgtypeslib/Makefile
  83         src/interfaces/ecpg/preproc/Makefile
  84         src/interfaces/libpq/Makefile
  85         src/tools/msvc/Mkvcbuild.pm
  86
  87
  88 Creating Back-Branch Release Notes
  89 ==================================
  90
  91 * Run src/tools/git_changelog to generate a list of relevant commits.
  92   You can also run 'git log' in each branch.  Be sure to use the --since
  93   branch tag and not the release date, as commits could have been done
  94   between branch stamping and the release date.
  95
  96 * On the git master branch, edit and create SGML markup for the most recent
  97   branch in that branch's release-N.N.sgml file.  Minor release notes
  98   should include more small change details because testing is limited.
  99
 100 * Copy this into older branches' release-N.N.sgml files, then remove
 101   items that do not apply based on commit logs for that branch.
 102
 103 * Add any older branch commits not in the newest branch.  This can be
 104   accomplished by diff'ing the newest and older branch commit logs and
 105   looking for lines that only appear in the older branch, e.g.:
 106
 107        diff commit-N.N.log commit-O.O.log | grep '^>'
 108
 109 * Copy the appropriate release-N.N.sgml files into each back branch SGML
 110   directory.
 111
 112
 113
 114 ---------------------------------------------------------------------------
 115
 116                        Library Version Changes
 117                        =======================
 118
 119 Major Version
 120 =============
 121
 122 The major version number should be updated whenever the source of the
 123 library changes to make it binary incompatible. Such changes include,
 124 but are not limited to:
 125
 126 1. Removing a public function or structure (or typedef, enum, ...)
 127
 128 2. Modifying a public functions arguments.
 129
 130 3. Removing a field from a public structure.
 131
 132 4. Adding a field to a public structure, unless steps have been
 133 previously taken to shield users from such a change, for example by
 134 such structures only ever being allocated/instantiated by a library
 135 function which would give the new field a suitable default value.
 136
 137 Adding a new function should NOT force an increase in the major version
 138 number. (Packagers will see the standard minor number update and install
 139 the new library.)  When the major version is increased all applications
 140 which link to the library MUST be recompiled - this is not desirable. When
 141 the major version is updated the minor version gets reset.
 142
 143 Minor Version
 144 =============
 145
 146 The minor version number should be updated whenever the functionality of
 147 the library has changed, typically a change in source code between releases
 148 would mean an increase in the minor version number so long as it does not
 149 require a major version increase.
 150
 151 Given that we make at least minor changes to our libraries in every major
 152 PostgreSQL version, we always bump all minor library version numbers at the
 153 start of each development cycle as a matter of policy.
 154
 155 Minimizing Changes
 156 ==================
 157
 158 When modifying public functions arguments, steps should be taken to
 159 maintain binary compatibility across minor PostgreSQL releases (e.g. the
 160 7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
 161 function:
 162
 163         void print_stuff(int arg1, int arg2)
 164         {
 165             printf("stuff: %d %d\n", arg1, arg2);
 166         }
 167
 168 If we wanted to add a third argument:
 169
 170         void print_stuff(int arg1, int arg2, int arg3)
 171         {
 172             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 173         }
 174
 175 Then doing it like this:
 176
 177         void print_stuff2(int arg1, int arg2, int arg3)
 178         {
 179             printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 180         }
 181
 182         void print_stuff(int arg1, int arg2)
 183         {
 184             print_stuff2(arg1, arg2, 0);
 185         }
 186
 187 would maintain binary compatibility. Obviously this would add a fair
 188 bit of cruft if used extensively, but considering the changes between
 189 minor versions would probably be worthwhile to avoid bumping library
 190 major version. Naturally in the next major version print_stuff() would
 191 assume the functionality and arguments of print_stuff2().
 192
 193
 194 Lee Kindness