← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to src/tools/RELEASE_CHANGES

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
        o check if 'gmake HISTORY.html' works for <link>s
 
14
 
 
15
* Update timezone data to match latest zic database and new
 
16
  Windows releases, if any (see src/timezone/README)
 
17
 
 
18
* Translation updates
 
19
        Translations are kept in the project "pgtranslation" on PgFoundry.
 
20
        1. Check out the messages module (of the right branch).
 
21
        2. Tag the messages: cvs tag -c RELx_y_z
 
22
        3. Check out the admin module.
 
23
        4. From babel.postgresql.org, download the "qualified list"
 
24
           for the respective branch.
 
25
        5. Run "sh .../admin/cp-po -L qualified-list-xxx.txt .../messages .../pgsql
 
26
        6. Commit.
 
27
 
 
28
 
 
29
For Major Releases
 
30
==================
 
31
(in addition to the above)
 
32
 
 
33
* Release notes
 
34
        o use git log or src/tools/git_changelog to find the relevant commits
 
35
        o check completion of items that have been marked as completed at
 
36
          http://wiki.postgresql.org/wiki/Todo
 
37
        o remove completed 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
        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
 
 
67
* Increment the major version number in src/tools/version_stamp.pl
 
68
 
 
69
* Run "src/tools/version_stamp.pl devel", then run autoconf
 
70
 
 
71
* Bump minor library versions, major if appropriate (see below)
 
72
        o src/interfaces/*/Makefile
 
73
        o src/interfaces/*/*/Makefile
 
74
 
 
75
 
 
76
Creating Back-Branch Release Notes
 
77
==================================
 
78
 
 
79
* Run src/tools/git_changelog to generate a list of relevant commits
 
80
 
 
81
* On the git master branch, edit and create SGML markup for the most recent
 
82
  branch in that branch's release-N.N.sgml file
 
83
 
 
84
* Copy this into older branches' release-N.N.sgml files, then remove
 
85
  items that do not apply based on commit logs for that branch (and add
 
86
  any that are needed)
 
87
 
 
88
* Copy the appropriate release-N.N.sgml files into each back branch
 
89
 
 
90
 
 
91
---------------------------------------------------------------------------
 
92
 
 
93
                       Library Version Changes
 
94
                       =======================
 
95
 
 
96
Major Version
 
97
=============
 
98
 
 
99
The major version number should be updated whenever the source of the
 
100
library changes to make it binary incompatible. Such changes include,
 
101
but are not limited to:
 
102
 
 
103
1. Removing a public function or structure (or typedef, enum, ...)
 
104
 
 
105
2. Modifying a public functions arguments.
 
106
 
 
107
3. Removing a field from a public structure.
 
108
 
 
109
4. Adding a field to a public structure, unless steps have been
 
110
previously taken to shield users from such a change, for example by
 
111
such structures only ever being allocated/instantiated by a library
 
112
function which would give the new field a suitable default value.
 
113
 
 
114
Adding a new function should NOT force an increase in the major version
 
115
number. (Packagers will see the standard minor number update and install
 
116
the new library.)  When the major version is increased all applications
 
117
which link to the library MUST be recompiled - this is not desirable. When
 
118
the major version is updated the minor version gets reset.
 
119
 
 
120
Minor Version
 
121
=============
 
122
 
 
123
The minor version number should be updated whenever the functionality of
 
124
the library has changed, typically a change in source code between releases
 
125
would mean an increase in the minor version number so long as it does not
 
126
require a major version increase.
 
127
 
 
128
Given that we make at least minor changes to our libraries in every major
 
129
PostgreSQL version, we always bump all minor library version numbers at the
 
130
start of each development cycle as a matter of policy.
 
131
 
 
132
Minimizing Changes
 
133
==================
 
134
 
 
135
When modifying public functions arguments, steps should be taken to
 
136
maintain binary compatibility across minor PostgreSQL releases (e.g. the
 
137
7.2 series, the 7.3 series, the 7.4/8.0 series). Consider the following
 
138
function:
 
139
 
 
140
        void print_stuff(int arg1, int arg2)
 
141
        {
 
142
            printf("stuff: %d %d\n", arg1, arg2);
 
143
        }
 
144
 
 
145
If we wanted to add a third argument:
 
146
 
 
147
        void print_stuff(int arg1, int arg2, int arg3)
 
148
        {
 
149
            printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 
150
        }
 
151
 
 
152
Then doing it like this:
 
153
 
 
154
        void print_stuff2(int arg1, int arg2, int arg3)
 
155
        {
 
156
            printf("stuff: %d %d %d\n", arg1, arg2, arg3);
 
157
        }
 
158
 
 
159
        void print_stuff(int arg1, int arg2)
 
160
        {
 
161
            print_stuff(arg1, arg2, 0);
 
162
        }
 
163
 
 
164
would maintain binary compatibility. Obviously this would add a fair
 
165
bit of cruft if used extensively, but considering the changes between
 
166
minor versions would probably be worthwhile to avoid bumping library
 
167
major version. Naturally in the next major version print_stuff() would
 
168
assume the functionality and arguments of print_stuff2().
 
169
 
 
170
 
 
171
Lee Kindness