docs/random/release

   1 GStreamer Release Policies (or: why we should become a country and pass laws)
   2 --------------------------
   3
   4 Development Period
   5 ------------------
   6 Development period is marked by having a fourth (nano) version number of 1.
   7 During development anything goes short of wiping the tree.
   8 Just try doing a few basic things :
   9 - make sure it builds for you !
  10 - check what you're about to commit with cvs -Q diff -r
  11 - preferably, keep an anonymous checkout around as well so you can
  12   immediately update and check if your changes work in a clean tree as well
  13
  14 Prerelease Period
  15 -----------------
  16 After a bit of development, people want a new release.  This generally happens
  17 when :
  18 - core developers get anxious to apply massive changes to the core bound
  19   to break everything
  20 - a few important plugins decide, as if by magic, to work again (avi, mad, ...)
  21 - Uraeus and thomasvs get tired of the general laziness
  22
  23 Also, this should only be allowed after passing a few sanity checks :
  24 - make distcheck should pass
  25 - rpms should build
  26 - FIXME: should debs be built here ? If so, how ?
  27
  28 At this time, we need to do a few prereleases for general checking by all
  29 interested developers.  To minimize the impact on the rest of the core hacking,
  30 we create a new CVS branch which will go through the pre-releases and finally
  31 contain the definitive tarball for that version.
  32
  33 TODO :
  34   - Decide on the next version number (major, minor or micro upgrade ?)
  35   - Get a fresh copy to do the necessary tests on
  36   - If this isn't on the stable branch (like for 0.6), then create a new branch;
  37     - with 0.3.3 as an example, tag is BRANCH-RELEASE-0_3_3
  38       cvs tag BRANCH-RELEASE-0_3_3-ROOT
  39       cvs tag -b BRANCH-RELEASE-0_3_3
  40     - update your local copy to the branch:
  41       cvs update -r BRANCH-RELEASE-0_3_3
  42   - Set the nano to 2 (in configure.ac, AS_VERSION)
  43   - If this is a release candidate for a new major version, override
  44     MAJOR/MINOR in configure.ac
  45   - Do all updates/patches/changes for the release tarball in this branch
  46   - Think of a good codename for the release
  47   - Check the bug lists:
  48     - The idea is to have all bugs for this milestone listed as fixed
  49     - Check all of the bug reports with this version as a milestone, and verify
  50       that these bugs are fixed, or reassign to a later milestone if not
  51     - Check later milestone bugs, and if any of them are fixed, reassign to
  52       this milestone
  53     - Check the list of bugs resolved with milestone HEAD, which should be
  54       assigned to an actual milestone
  55   - create a new $(version).xml file in www/src/htdocs/releases/$(module)
  56     and add that to cvs
  57   - Start updating the release notes on the www cvs tree
  58     - create the base xml file in www/htdocs/releases/$/module)/$(version).xml
  59     - add the generated targets (text and html) for this to the Makefile.am
  60     - grepping ChangeLog for contributors:
  61  grep "<.*>" ChangeLog | perl -i -p -e 's@\d*-\d*-\d*\s*(.*)\s*<.*$@$1@' | sort | uniq
  62     - use www/bin/bugzilla (module) (version) to get an xml list of the
  63       bugs fixed in this version, and add it to the release .xml
  64   - depending on how the API has changed update the libtool versioning
  65     in configure.ac, AS_LIBTOOL
  66     (Look at the libtool info page about versioning for guidelines)
  67     (if MAJOR/MINOR version has changed, however, you can reset all to 0)
  68   - FIXME: autotools have latest config.{guess,sub}
  69            This is needed in order to support newer platforms.
  70            On Debian install the autotools-dev package to get these.
  71            Someone please add some more useful info here on how to do this
  72   - while (IS_PRERELEASE)
  73     {
  74       - increase the nano number (starting with 2)
  75       - check out a fresh anonymous copy
  76         cvs -d:pserver:anonymous@cvs.gstreamer.sf.net:/cvsroot/gstreamer \
  77             co -rBRANCH-RELEASE-0_3_3 gstreamer
  78       - make distcheck, rpm build should pass, from a FRESH cvs tree
  79       - media tests should be done
  80       - source tarball should be installed and tested
  81       - rpms should be installed and tested
  82       - put up tarball for a day
  83     }
  84
  85
  86 Release Period
  87 --------------
  88 When we're satisfied with the prereleases, it's time to make the final tarball.
  89 It's very important that the tarball we put out is fully checked, works as
  90 planned, and generally is generated only ONCE by someone with a relatively
  91 clean (and reference) system.  We don't want to put out more than one tarball
  92 with the same name.
  93
  94 TODO :
  95   - give the latest prerelease another good testing
  96   - proofread the release notes
  97   - run bugzilla with the correct module and milestone and include
  98     the output in the release notes
  99     bin/bugzilla gstreamer 0.7.5 >> src/htdocs/releases/gstreamer/0.7.5.xml
 100     then edit it
 101   - copy  www/htdocs/releases/$(module)/$(version) to RELEASE
 102   - copy the list of changes and add them to NEWS
 103   - update the ChangeLog and add === release (version) ===
 104   - update web site docs
 105     - release-specific docs should go in CVS
 106     - change docs/current symlink
 107   - remove the nano version number in configure.ac, AS_VERSION
 108   - tag tree
 109     for example for 0.6.3 :
 110            cvs tag RELEASE-0_6_3
 111   - run "make release", build rpms
 112   - run "make upload" from gstreamer/docs to get the new docs online
 113   - change www/src/htdocs/entities.gst with the new version numbers
 114   - add a news item to the news.xml
 115
 116 Post-Release Period
 117 -------------------
 118 Time to bring the new version under the eyes of the public.
 119
 120 TODO :
 121   - FIXME: should we md5 the tarballs?
 122   - upload to sourceforge
 123       upload.sourceforge.net/incoming
 124       administer the release
 125
 126   - FIXME: announcements
 127     - gstreamer-{devel, announce} : a simple mail with RELEASE
 128     - freshmeat
 129     - linux-audio-dev (if it's a big release) : a simple mail with RELEASE
 130     - gnome lists (?)
 131     - lwn (if it's a big release)
 132   - Kick back, have a party, enjoy people coming in on IRC telling us how
 133     GStreamer rocks.
 134   - Later on, if necessary, merge back latest release branch to current dev
 135     branch (if patches to source were made)
 136
 137     TWO WAYS:
 138     A)
 139        * get a diff between the branch root and the final release:
 140          cvs diff -r BRANCH-RELEASE-0_7_5-ROOT -r RELEASE-0_7_5 > patch
 141        * fix up this patch (remove RELEASE)
 142        * and apply it to the HEAD branch
 143        * update nano version to 1 in configure.ac
 144
 145     B)
 146        * change to a HEAD branch, make sure it's updated
 147        * cvs diff -R -r RELEASE-0_3_4-30SECONDFRENCHMAN
 148          gives a list of differences between head and release tag,
 149          stuff with > is how it's in HEAD, < is in the rel branch
 150
 151        * cvs update -j BRANCH-RELEASE-0_3_4
 152          merges the difference made in that branch to the current source
 153          this is what you want to use when merging back the branch
 154          resolve conflicts and commit
 155
 156 Some various random comments that might or might not make sense :
 157
 158 - Should work:
 159   * autoconf feature to allow building outside source dir
 160
 161 - Package version policy
 162   - Use major.minor.micro versioning
 163   - Before 1.0.0, Update micro until code and API are fairly stable,
 164     then update minor.
 165   - After 1.0.0,
 166     Update major when code and api hit new level of stability or major features.
 167     Update minor on API changes.
 168     Update micro on API-compatible changes.