/[guile]/guile/workbook/build/release.text
ViewVC logotype

Diff of /guile/workbook/build/release.text

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by ttn, Wed May 15 13:04:30 2002 UTC revision 1.3 by rlb, Thu May 16 21:43:31 2002 UTC
# Line 1  Line 1 
1  Some Notes About Release  Releasing Guile
2  ========================  ===============
3    
4  Index  * Index
5   - Names    * Introduction
6   - Platforms    * Policy
7   - Indications    * Names
8   - Requirements    * Process
9   - Checklist      * Deciding to release
10   - Notifications      * Producing the release (the building and testing cycle)
11        * Announcing the release
12      * Volunteer Testers
13    
14    * Introduction
15    
16      The release manager and the release management process should always
17      try to be more a help than a hindrance, but in order to be able to
18      make sure that we have quality releases, and that we get them out
19      the door in a reasonable amount of time, the release manager has to
20      have *some* authority with respect to a few issues.  As with all
21      policy, it is likely true that "the *less* process we can have, the
22      better" -- to paraphrase a famous quote -- "as simple as possible,
23      but no simpler".
24    
25  Names    Accordingly the Guile release policy will start small and be
26  -----    reworked as needed based on our experiences.  No one is going to be
27      able to dream up the perfect system for this a-priori.
28    
29  Maybe we should name Guile releases after entertaining poisons:  * Policy
 absinthe, etc.  However, the first release containing the module  
 system should be called Godot: "This is the one you've been waiting  
 for."  
30    
31      - The release manager will provide input to help decide when it
32        might be time to branch for a release.  (Now that we have a more
33        sophisticated bug tagging system, we won't normally branch until
34        until all currently known release-critical issues have been
35        resolved.  This should help limit the time between branch and
36        release, which is in general a good idea.)
37    
38  Platforms    - The release manager will handle creating the stable branch when
39  ---------      finally deemed appropriate.
40    
41  For test builds:    - Once a release branch has been made, no one other than the release
42        manager or a member of the Guile maintainer committee should check
43        in changes to that branch without approval from the release
44        manager, unless those fixes are for release critical bugs that
45        they're supposed to be fixing -- where "supposed to be fixing"
46        means that the release manager already knows about what they're
47        doing, and "approval" doesn't have to be all that formal.  For
48        example, popping up on irc, talking to the release manager and
49        then posting to guile-devel that you're fixing "XZY" in the stable
50        branch after consultation on IRC with the release manager, is just
51        fine.
52    
53  SunOS (gcc and pcc) --- galapas.ai.mit.edu    - No one should modify entries in the workbook/tasks/TODO section
54  Solaris (gcc and SUN cc) --- saturn.ai.mit.edu      for a branched stable release target, nor add/delete the
55  NetBSD (gcc) --- repo-man.ai.mit.edu (use /home/repo/jimb)      corresponding bugs/* release-critical tags without the approval of
56  HP/UX (gcc, HP cc) --- nutrimat.gnu.ai.mit.edu      the release manager.  Note that once we get to the point where we
57        branch much more closely to the stable release, this shouldn't be
58        a big issue.
59    
60  These gentlemen have kindly offered to do pre-release testing:    - workbook/tasks/TODO and a scan of workbook/bugs/* for the relevant
61        release-critical tags should always provide a *complete* picture
62        of what's holding up a release.  For those that don't have direct
63        CVS access, please make sure you ask someone who does to edit TODO
64        or bugs/* accordingly when appropriate.  (Eventually we will
65        probably have a script that will automatically generate a list of
66        the items holding up a release.)
67    
68  Tom Tromey <tromey@cygnus.com>:    - whenever all the currently listed release TODO items and release
69        critical bugs have been resolved (by whatever means), the release
70        manager will build, upload and announce a pre-release beta.
71    
72    alphaev5-unknown-linux-gnu    - If after a pre-release beta has been out for two weeks and no new
73    hppa1.1-hp-hpux10.20      agreed-upon release-critical issues arise, the release manager
74    hppa1.1-hp-hpux11.00      will build, upload, and announce the stable release.  If
75    mips-sgi-irix5.3      release-critical issues do arise, then at the release manager's
76    powerpc-ibm-aix4.2.0.0      discretion, fixing them may or may not require another beta
77    powerpc-unknown-linux-gnu      pre-release (i.e. an endian fix might, but a minor documentation
78    sparc-sun-solaris2.6      fix probably wouldn't).
   i686-pc-linux-gnu  
   mips-sgi-irix6.3  
   sparc-sun-sunos4.1.4  
79    
80  Perry Metzger <perry@piermont.com>    - The release manager will build, upload, and announce the stable
81        release and manage future stable point releases.
82    
83    NetBSD  * Names
84    
85      Maybe we should name Guile releases after entertaining poisons:
86      absinthe, etc.  However, the first release containing the module
87      system should be called Godot: "This is the one you've been waiting
88      for."
89    
90  Indications [fixme:rlb]  * Process
 -----------  
91    
92  A release can be for whim, but it's better if there are some pre-conditions    * Deciding to release
 that "indicate" the release (like certain symptoms indicate using medication).  
 Typical indications are:  
93    
94  * new feature freeze      As mentioned in Policy (above), one thing that should gate a
95  * documentation sync'ed      release is whether or not all the release critical bugs and TODO
96  * various scripts are happy      items have been resolved.  A stable branch will not normally be
97  * change moderated by release manager      made until then.
   * discussion required for non-bugfix changes  
   * all RC bugs fixed  
98    
99        However, there should be other criteria involved in deciding when
100        to release, though sometimes it may be something as simple as a
101        large number of accumulated bugfixes.
102    
103  Requirements [fixme:rlb]      Other possible reasons:
 ------------  
104    
105  * some kind of say about what does and doesn't go into the stable branch        - impending major changes to the development tree.
106  * ...        - new and improved documentation.
107          - major new features finished.
108    
109        In general, the TODO will be our record of what's planned for the
110        next release (what must be done before then), and should be
111        debated and updated accordingly after every major release.
112    
 Release Checklist  
 -----------------  
113    
114  There are basically three phases to doing a release:    * Producing the release (the building and testing cycle)
115    
116  * "BRANCHING": Creating a stable development branch in CVS.      * Overview
117    
118  * "SPIFFING": Updating NEWS, README, INSTALL.  Running tests.  Getting        There are basically three phases to doing a release:
   people to try builds on various machines.  Getting everything  
   straightened up.  
119    
120  * "PUNTING": Updating the version numbers.  Tagging the sources.  Asking        - "BRANCHING": Creating a stable development branch in CVS.
   the FSF to put the disty on ftp.gnu.org.  Posting announcements.  
121    
122  The "Spiffing" phase you might go through several times as you        - "SPIFFING": Updating NEWS, README, INSTALL.  Running tests.
123  discover problems.  The "Branching" and "Punting" phases you do only          Getting people to try builds on various machines.  Getting
124  once.          everything straightened up.
125    
126  Branching checklist:        - "PUNTING": Updating the version numbers.  Tagging the sources.
127            Asking the FSF to put the disty on ftp.gnu.org.  Posting
128            announcements.
129    
130  * Announce when you're about to make the branch so that you have a        The "Spiffing" phase you might go through several times as you
131    greater chance of people holding off on edits during the short        discover problems.  The "Branching" and "Punting" phases you do
132    period while you're branching.        only once.
133    
134  * Make sure you're on the main trunk (see HACKING), and then create      * Branching
   the branch-root tag.  i.e. -r branch-root_release-1-6.  (Add the  
   exact command here next time I do it.)  
135    
136  * Now create the branch with the branch tag. i.e. -r        Once it's been determined that it is time for a release (see
137    branch_release-1-6.  (Add exact command here next time I do it.)        "Deciding to release" above), here's what to do:
138    
139  * Change the version numbers in GUILE-VERSION and README on the main          - Announce when you're about to make the branch so that you
140    branch to reflect the new unstable version i.e. 1.7.0, if you're            have a greater chance of people holding off on edits during
141    currently creating the 1.6.X branch.            the short period while you're branching.
142    
143  Spiffing checklist:          - Make sure you're on the main trunk (see HACKING), and then
144              create the branch-root tag.  i.e. -r
145              branch-root_release-1-6.  (Add the exact command here next
146              time I do it.)
147    
148    NOTE: Unless you're *SURE* you know what you're doing, please          - Now create the branch with the branch tag. i.e. -r
149    perform the following actions in order.  The ordering is important            branch_release-1-6.  (Add exact command here next time I do
150    in places below.            it.)
151    
152  * Make sure you're working on the stable branch (see HACKING for          - Change the version numbers in GUILE-VERSION and README on
153    details).  Note that after following the branch checklist above, you            the main branch to reflect the new unstable version
154    won't necessarily be.            i.e. 1.7.0, if you're currently creating the 1.6.X branch.
155    
156  * Make sure you've got the latest files "cvs -qz3 update -Pd".      * Spiffing (i.e. beta testing)
157    
158  * Check for files that have changed a lot, but do not have up-to-date        NOTE: Unless you're *SURE* you know what you're doing, please
159    copyright notices.  This can be as simple as doing:        perform the following actions in order.  The ordering is
160          grep 'Copyright' * | grep -v 1999        important in places.
   and looking for files you know you've worked on a lot.  
161    
162  * Make sure NEWS, INSTALL, AUTHORS and THANKS and the docs are up to date:        * Update the source.
   + Scan the ChangeLogs for user-visible changes, marked with an asterisk  
     at the left margin.  
   + Update NEWS and the Texinfo documentation as appropriate.  
   + Check for any [[incomplete]] sections of NEWS.  
   + Fact-check INSTALL.  
   + Make sure AUTHORS and THANKS are up-to-date (see also TODO).  
   + Remove finished items from TODO (those marked w/ "+").  
163    
164  * Make sure the downloading addresses and filenames in README are          - Make sure you're working on the stable branch (see HACKING for
165    current.  (But don't bump the version number yet.  We do that below.)            details).  Note that after following the branch checklist
166              above, you won't necessarily be.
167    
168  * Check that the versions of aclocal, automake, autoconf, and autoheader          - Make sure you've got the latest files "cvs -qz3 update -Pd".
   in your PATH match those given in HACKING.  Note that the `make  
   dist' process always invokes these tools, even when all the  
   generated files are up to date.  
   Make specifically sure that the files in libltdl are generated using  
   the same tools as the rest.  
169    
170  * Build the test distribution          - Check for files that have changed a lot, but do not have up-to-date
171              copyright notices.  This can be as simple as doing:
172                grep 'Copyright' * | grep -v 1999
173              and looking for files you know you've worked on a lot.
174    
175    NOTE: during this section, don't commit any of your changes to CVS          - Make sure NEWS, INSTALL, AUTHORS and THANKS and the docs are
176    until the instructions tell you to below.  This is important so that            up to date:
177    someone doesn't check out CVS and think that they have a finished              - Scan the ChangeLogs for user-visible changes, marked with
178    copy of a particular release when they actually don't.                an asterisk at the left margin.
179                - Update NEWS and the Texinfo documentation as appropriate.
180                - Check for any [[incomplete]] sections of NEWS.
181                - Fact-check INSTALL.
182                - Make sure AUTHORS and THANKS are up-to-date (see also TODO).
183                - Remove finished items from TODO (those marked w/ "+").
184    
185    * update GUILE-VERSION to reflect the current test distribution, but          - Make sure the downloading addresses and filenames in README
186      don't commit this change to CVS yet (see below).  For example,            are current.  (But don't bump the version number yet.  We do
187      just before the 1.6.0 release, we went through some number of            that below.)
     1.5.X test releases.  
188    
189    * Run ./autogen.sh to rebuild all generated files in the source tree.          - Check that the versions of aclocal, automake, autoconf, and
190              autoheader in your PATH match those given in HACKING.  Note
191              that the `make dist' process always invokes these tools,
192              even when all the generated files are up to date.  Make sure
193              that the files in libltdl are generated using the same tools
194              as the rest.
195    
196    * configure the source tree for build in the same tree with these          - Check the library version numbers
     configuration options:  
       --enable-maintainer-mode --enable-debug-malloc --with-threads  
       --enable-error-on-warning --prefix=/wherever/you/want  
197    
198    * Build the tree.  (If the above two steps are not done first, the            - Make sure the shared library libtool versioning numbers
199      dependencies won't be properly included in the generated              are correct, but first make sure you understand "Libtool's
200      Makefile.in files.)              versioning system" in the libtool info pages.  Guile is
201                going to be versioning it's shared libraries
202                independently, so follow the libtool rules for choosing
203                version numbers, but make sure to keep in mind that not
204                everyone is as good about this as they should be.  In any
205                case, note that if your library passes through data
206                structures that were produced by some sub-library, and
207                that sub-libraries data has changed in a publically
208                incompatible way, then this may mean that *your* library's
209                API has changed in a publically incompatible way.
210    
211    * Run "make" and "make check".            - In general, there will be a number of libraries in guile
212                that will have to be versioned, and it would be best if
213                the people who know the most about the individual libs
214                decide what the apropriate CURRENT, REVISION, and AGE
215                numbers for each one are.  In general, though, you have to
216                be conservative.  If no one is sure that the libs are
217                still compatible, then you *must* make the appropriate
218                changes under the assumption that they're not.  Getting
219                this wrong is very BAD(TM).
220    
221    * Run "make dist".        * Build the beta test distribution
222    
223    * test the resultant tarfile yourself using the instructions under          NOTE: during this section, don't commit any of your changes to
224      "Testing a release candidate tarfile" below.          CVS until the instructions tell you to below.  This is
225            important so that someone doesn't check out CVS and think that
226            they have a finished copy of a particular release when they
227            actually don't.
228    
229    * Add a "Guile beta N.M released." entry to the top-level ChangeLog.          - update GUILE-VERSION to reflect the current test
230              distribution, but don't commit this change to CVS yet (see
231              below).  For example, just before the 1.6.0 release, we went
232              through some number of 1.5.X test releases.
233    
234    * Now commit all your changes to CVS.          - Run ./autogen.sh to rebuild all generated files in the source tree.
235    
236    * Tag the release "cvs tag release_1-5-2".          - configure the source tree for build in the same tree with
237              these configuration options: --enable-maintainer-mode
238              --enable-debug-malloc --with-threads
239              --enable-error-on-warning
240              --prefix=/wherever/you/want
241    
242    * Run 'make dist' again to get the official tarfile.          - Build the tree.  (If the above two steps are not done first,
243              the dependencies won't be properly included in the generated
244              Makefile.in files.)
245    
246  * Give the test disty to various people to try.  They should follow          - Run "make" and "make check".
   the same instructions under "Testing a release candidate tarfile"  
   below.  
247    
248  * Testing a release candidate tarfile:          - Run "make dist".
249    
250    * Unset GUILE_LOAD_PATH.        * Test the beta release candidate tarfile.
251    
252    * Remove automake and autoconf from your path, or turn off their          - Unset GUILE_LOAD_PATH.
     execute bits, or something.  (Users must be able to build from the  
     tarfile without installing those tools.)  As an example, you could  
     disable the tools during the test like so:  
253    
254        mkdir /tmp/stub          - Remove automake and autoconf from your path, or turn off
255        cat > /tmp/stub/do-nothing <<EOF            their execute bits, or something.  (Users must be able to
256        #!/bin/sh            build from the tarfile without installing those tools.)  As
257        echo warning: $0 called            an example, you could disable the tools during the test like
258        sleep 10            so:
       exit 0  
       EOF  
       chmod +x /tmp/stub/do-nothing  
       ln /tmp/stub/do-nothing /tmp/stub/automake  
       ln /tmp/stub/do-nothing /tmp/stub/autoconf        # etc  
       PATH=/tmp/stub:$PATH  
259    
260    * Configure, "make", "make check", and "make install".  Make sure to              mkdir /tmp/stub
261      remove your previous install tree before the "make install".              cat > /tmp/stub/do-nothing <<EOF
262                #!/bin/sh
263                echo warning: $0 called
264                sleep 10
265                exit 0
266                EOF
267                chmod +x /tmp/stub/do-nothing
268                ln /tmp/stub/do-nothing /tmp/stub/automake
269                ln /tmp/stub/do-nothing /tmp/stub/autoconf  # etc
270                PATH=/tmp/stub:$PATH
271    
272    * Make sure LD_LIBRARY_PATH doesn't include anything unnecessary.          - Configure, "make", "make check", and "make install".  Make
273              sure to remove your previous install tree before the "make
274              install".
275    
276    * Run the test suite on the installed version.          - Make sure LD_LIBRARY_PATH doesn't include anything
277          ./check-guile -i [INSTALL_PATH]/bin/guile            unnecessary.
278    
279    * Look at the install tree (with "find | sort" or similar) and make          - Run the test suite on the installed version.
280      sure nothing seems obviously amiss.              ./check-guile -i [INSTALL_PATH]/bin/guile
281    
282    * Check that the dependencies in guile-readline/Makefile look OK.          - Look at the install tree (with "find | sort" or similar) and
283      (We currently use a kludge which edits the dependencies generated            make sure nothing seems obviously amiss.
     by automake so that Guile can be built in a directory separate  
     from the source tree also with non-GNU make programs.)  
284    
285    * Make sure readline works.          - Check that the dependencies in guile-readline/Makefile look
286              OK.  (We currently use a kludge which edits the dependencies
287              generated by automake so that Guile can be built in a
288              directory separate from the source tree also with non-GNU
289              make programs.)
290    
291    * You might try the example code in the doc directory.          - Make sure readline works.
292    
293  Once you've got a disty that seems pretty solid:          - You might try the example code in the doc directory.
294    
295  * Make sure the shared library libtool versioning numbers are correct,        * Update CVS and tag the beta release.
   but first make sure you understand "Libtool's versioning system" in  
   the libtool info pages.  Guile is going to be versioning it's shared  
   libraries independently, so follow the libtool rules for choosing  
   version numbers, but make sure to keep in mind that not everyone is  
   as good about this as they should be.  In any case, note that if  
   your library passes through data structures that were produced by  
   some sub-library, and that sub-libraries data has changed  
   in a publically incompatible way, then this may mean that *your*  
   library's API has changed in a publically incompatible way.  
296    
297  * In general, there will be a number of libraries in guile that will          When you get a tarfile that checks out OK.
   have to be versioned, and it would be best if the people who know  
   the most about the individual libs decide what the apropriate  
   CURRENT, REVISION, and AGE numbers for each one are.  In general,  
   though, you have to be conservative.  If no one is sure that the  
   libs are still compatible, then you *must* make the appropriate  
   changes under the assumption that they're not.  Getting this wrong  
   is very BAD(TM).  
298    
299  * Make the final update to the version numbers in GUILE-VERSION and          - Add a "Guile beta N.M
300    README.  (There are many places in README that need updating!).  See            released." entry to the top-level ChangeLog.
   HACKING for more information on how the version numbers are to be  
   chosen.  
301    
302  * Reformat the names in THANKS.          - Now commit all your changes to CVS (this will also commit
303              the new GUILE-VERSION).
304    
305  * Do a `cvs -z3 update -Pd' of the whole tree, to look for any stray          - Tag the release "cvs tag release_1-5-2".
   uncommitted or accidental changes.  
306    
307  * Commit your changes.          - Run 'make dist' again to get the official tarfile.
308    
309  * Make one last test distribution.          - Upload the tarfile.
310    
311  Punting checklist:          - Update the News on www.guile.org.
312    
313  * Add "Guile X.Y.Z released." entry to the top-level ChangeLog, and commit it.          - Announce the beta release in the places appropriate for a
314              beta test (fixme: elaborate -- i.e. guile-user, guile-devel,
315              etc., and put a sample beta release msg somewhere).  The
316              testers should follow the same instructions under "Test the
317              beta release candidate tarfile" above.
318    
319  * Tag the entire source tree with a tag of the form "release_X-Y-Z",        * Decide if we're ready for the final release
   i.e for release 1.6.1, use release_1-6-1  
320    
321  * Do a 'make dist'.          If after two weeks, no new agreed upon release critical issues
322            have surfaced, proceed to "Punting" below, otherwise fix the
323            issues, and return to "Spiffing" above.
324    
325  * Put the distribution up for FTP somewhere, and send mail to      * Punting (the final stable release)
   ftp-upload@gnu.org, asking them to put it on prep.  
326    
327          - Make the final update to the version numbers in GUILE-VERSION
328            and README.  (There are many places in README that need
329            updating!).  See HACKING for more information on how the
330            version numbers are to be chosen.
331    
332          - Add a "Guile X.Y.Z released." entry to the top-level
333            ChangeLog.
334    
335  Notifications        - Now commit all your changes to CVS.
 -------------  
336    
337  * Send an announcement message to gnu-announce@gnu.org.  Put a brief        - Tag the entire source tree with a tag of the form "release_X-Y-Z",
338    summary of the changes in this release first, then "Obtaining          i.e for release 1.6.1, use release_1-6-1
   Guile", "Thanks", "About This Distribution," and "Nightly  
   Snapshots."  If I remember correctly, the moderator will delay it  
   until the distribution appears on ftp.gnu.org.  The announcement  
   text should be mostly taken from Guile's README file.  
339    
340  * Notify freshmeat.net, although they're probably watching anyway.        - Do a 'make dist'.
   (They got the 1.3 release just fine.)  I have no idea if  
   www.bowerbird.com.au will be something anyone refers to, but Guile  
   does have an entry there.  
341    
342  * update ./guile-projects-entry and mail to guile-projects@glug.org        - Upload the tarfile.
343    
344  * update webpage news page        - Update the News on www.guile.org.
345    
346      * Announcing the release
347    
348        - Send an announcement message to gnu-announce@gnu.org.  Put a
349          brief summary of the changes in this release first, then
350          "Obtaining Guile", "Thanks", "About This Distribution," and
351          "Nightly Snapshots."  If I remember correctly, the moderator
352          will delay it until the distribution appears on ftp.gnu.org.
353          The announcement text should be mostly taken from Guile's README
354          file.
355    
356        - Notify freshmeat.net, although they're probably watching anyway.
357          (They got the 1.3 release just fine.)  I have no idea if
358          www.bowerbird.com.au will be something anyone refers to, but
359          Guile does have an entry there.
360    
361        - update ./guile-projects-entry and mail to guile-projects@glug.org
362    
363        - update webpage news page
364    
365    * Volunteer Testers
366    
367      For test builds:
368    
369      SunOS (gcc and pcc) --- galapas.ai.mit.edu
370      Solaris (gcc and SUN cc) --- saturn.ai.mit.edu
371      NetBSD (gcc) --- repo-man.ai.mit.edu (use /home/repo/jimb)
372      HP/UX (gcc, HP cc) --- nutrimat.gnu.ai.mit.edu
373    
374      These gentlemen have kindly offered to do pre-release testing:
375    
376      Tom Tromey <tromey@cygnus.com>:
377    
378        alphaev5-unknown-linux-gnu
379        hppa1.1-hp-hpux10.20
380        hppa1.1-hp-hpux11.00
381        mips-sgi-irix5.3
382        powerpc-ibm-aix4.2.0.0
383        powerpc-unknown-linux-gnu
384        sparc-sun-solaris2.6
385        i686-pc-linux-gnu
386        mips-sgi-irix6.3
387        sparc-sun-sunos4.1.4
388    
389      Perry Metzger <perry@piermont.com>
390    
391        NetBSD
392    
393    
394    
395    
396    
397    --
398    Local Variables:
399    mode: outline
400    outline-regexp: "[ ]*[*] "
401    End:

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26