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 - thaytan or thomasvs get tired of being lazy.
  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 RELEASE PROCEDURE:
  34 -----------------
  35
  36 - www/bin/new-release is a release helper script.  It automates a lot of the
  37   tedious work.  Now releasing looks like this:
  38
  39 - before release:
  40   - make sure all blocker bugs for that release are fixed or deferred
  41   - make sure you have a local copy of all online files
  42   - bin/new-release (module) (version) (checkoutdir) (release name)
  43     - updates cvs
  44     - allows you to update versioning in configure.ac
  45     - rebuilds
  46     - updates ChangeLog
  47     - adds a new releases/module/version.xml file and lets you edit
  48       --> here you add/fix up the features (from ChangeLog) and check
  49           contributors
  50     - allows you to update NEWS file with snippets from RELEASE
  51       --> copy stuff
  52     - rebuilds docs for plugins
  53     - rolls release tarballs and puts them in the local www/data tree
  54     - uploads docs to website
  55     - commits changes to po files
  56     - shows you a diff for evaluation
  57
  58   - build packages to test
  59
  60 - release:
  61   - cvs commit in the tree
  62   - tag tree
  63     for example for 0.6.3 :
  64            cvs tag RELEASE-0_6_3
  65   - bump nano number, commit
  66   - if working in the "stable" release branch, update to this tag to freeze it:
  67     cvs up -r RELEASE-0_6_3
  68   - sync source and packages to website
  69   - add entry on website; commit additions to website
  70   - change versions in www/src/htdocs/entities.gst
  71   - add versions and milestones in bugzilla
  72   - Send release announcements to:
  73     gstreamer-devel@lists.sourceforge.net gstreamer-announce@lists.sourceforge.net kde-multimedia@kde.org gnome-multimedia@gnome.org
  74   - Update freshmeat with new releases (get Uraeus to do it)
  75
  76
  77 Old release notes - superceded by the www/bin/new-release script.
  78 ----------------------------------------------------------------
  79
  80 TODO :
  81   - Decide on the next version number (major, minor or micro upgrade ?)
  82   - Get a fresh copy to do the necessary tests on
  83   - If this isn't on the stable branch (like for 0.6), then create a new branch;
  84     - with 0.3.3 as an example, tag is BRANCH-RELEASE-0_3_3
  85       cvs tag BRANCH-RELEASE-0_3_3-ROOT
  86       cvs tag -b BRANCH-RELEASE-0_3_3
  87     - update your local copy to the branch:
  88       cvs update -r BRANCH-RELEASE-0_3_3
  89   - Set the nano to 2 (in configure.ac, AS_VERSION)
  90   - If this is a release candidate for a new major version, override
  91     MAJOR/MINOR in configure.ac
  92   - Do all updates/patches/changes for the release tarball in this branch
  93   - Think of a good codename for the release
  94   - Check the bug lists:
  95     - The idea is to have all bugs for this milestone listed as fixed
  96     - Check all of the bug reports with this version as a milestone, and verify
  97       that these bugs are fixed, or reassign to a later milestone if not
  98     - Check later milestone bugs, and if any of them are fixed, reassign to
  99       this milestone
 100     - Check the list of bugs resolved with milestone HEAD, which should be
 101       assigned to an actual milestone
 102   - create a new $(version).xml file in www/src/htdocs/releases/$(module)
 103     and add that to cvs
 104   - Start updating the release notes on the www cvs tree
 105     - create the base xml file in www/htdocs/releases/$/module)/$(version).xml
 106     - grepping ChangeLog for contributors:
 107  grep "<.*>" ChangeLog | perl -i -p -e 's@\d*-\d*-\d*\s*(.*)\s*<.*$@$1@' | sort | uniq
 108     - use www/bin/bugzilla (module) (version) to get an xml list of the
 109       bugs fixed in this version, and add it to the release .xml
 110   - depending on how the API has changed update the libtool versioning
 111     in configure.ac, AS_LIBTOOL
 112     (Look at the libtool info page about versioning for guidelines)
 113     (if MAJOR/MINOR version has changed, however, you can reset all to 0)
 114   - FIXME: autotools have latest config.{guess,sub}
 115            This is needed in order to support newer platforms.
 116            On Debian install the autotools-dev package to get these.
 117            Someone please add some more useful info here on how to do this
 118   - while (IS_PRERELEASE)
 119     {
 120       - increase the nano number (starting with 2)
 121       - check out a fresh anonymous copy
 122         cvs -d:pserver:anonymous@cvs.gstreamer.sf.net:/cvsroot/gstreamer \
 123             co -rBRANCH-RELEASE-0_3_3 gstreamer
 124       - make distcheck, rpm build should pass, from a FRESH cvs tree
 125       - media tests should be done
 126       - source tarball should be installed and tested
 127       - rpms should be installed and tested
 128       - .2 tarball should be submitted to translation project
 129       - put up tarball for a day
 130     }
 131
 132
 133 Release Period
 134 --------------
 135 When we're satisfied with the prereleases, it's time to make the final tarball.
 136 It's very important that the tarball we put out is fully checked, works as
 137 planned, and generally is generated only ONCE by someone with a relatively
 138 clean (and reference) system.  We don't want to put out more than one tarball
 139 with the same name.
 140
 141 TODO :
 142   - give the latest prerelease another good testing
 143   - proofread the release notes
 144   - run bugzilla with the correct module and milestone and include
 145     the output in the release notes
 146     bin/bugzilla gstreamer 0.7.5 >> src/htdocs/releases/gstreamer/0.7.5.xml
 147     then edit it
 148   - verify all new translations are in and po files are updated
 149   - run win32-update from toplevel to copy new versions and enum files
 150   - copy  www/htdocs/releases/$(module)/$(version) to RELEASE
 151   - copy the list of changes, bugs fixed, and API changes and add them to NEWS
 152   - update the ChangeLog to account for NEWS, RELEASE, and configure.ac,
 153     mentioning the release name
 154   -  add === release (version) === to ChangeLog
 155   - update web site docs
 156     - release-specific docs should go in CVS
 157     - change docs/current symlink
 158   - remove the nano version number in configure.ac, AS_VERSION
 159   - cvs commit
 160   - tag tree
 161     for example for 0.6.3 :
 162            cvs tag RELEASE-0_6_3
 163   - run "make release", build rpms
 164   - install on gnome's ftp
 165   - for plugins docs: run "make update" in docs/plugins to update version info
 166   - for docs: run "make upload" from gstreamer/docs to get the new docs online
 167   - change www/src/htdocs/entities.gst with the new version numbers
 168   - change www/src/htdocs/bugs/bugs.xml and add a new milestone
 169   - possibly add new version and milestone to bugzilla
 170   - add a news item to the news.xml
 171
 172 Post-Release Period
 173 -------------------
 174 Time to bring the new version under the eyes of the public.
 175
 176 TODO :
 177   - FIXME: should we md5 the tarballs?
 178   - upload to sourceforge
 179       upload.sourceforge.net/incoming
 180       administer the release
 181
 182   - FIXME: announcements
 183     - gstreamer-{devel, announce} : a simple mail with RELEASE
 184     - freshmeat
 185     - linux-audio-dev (if it's a big release) : a simple mail with RELEASE
 186     - gnome lists (?)
 187     - lwn (if it's a big release)
 188   - send mail for translators with URL to .tar.bz2:
 189     translation@iro.umontreal.ca
 190   - Kick back, have a party, enjoy people coming in on IRC telling us how
 191     GStreamer rocks.
 192   - Later on, if necessary, merge back latest release branch to current dev
 193     branch (if patches to source were made)
 194
 195     TWO WAYS:
 196     A)
 197        * get a diff between the branch root and the final release:
 198          cvs diff -r BRANCH-RELEASE-0_7_5-ROOT -r RELEASE-0_7_5 > patch
 199        * fix up this patch (remove RELEASE)
 200        * and apply it to the HEAD branch
 201        * update nano version to 1 in configure.ac
 202
 203     B)
 204        * change to a HEAD branch, make sure it's updated
 205        * cvs diff -R -r RELEASE-0_3_4-30SECONDFRENCHMAN
 206          gives a list of differences between head and release tag,
 207          stuff with > is how it's in HEAD, < is in the rel branch
 208
 209        * cvs update -j BRANCH-RELEASE-0_3_4
 210          merges the difference made in that branch to the current source
 211          this is what you want to use when merging back the branch
 212          resolve conflicts and commit
 213
 214 Some various random comments that might or might not make sense :
 215
 216 - Should work:
 217   * autoconf feature to allow building outside source dir
 218
 219 - Package version policy
 220   - Use major.minor.micro versioning
 221   - Before 1.0.0, Update micro until code and API are fairly stable,
 222     then update minor.
 223   - After 1.0.0,
 224     Update major when code and api hit new level of stability or major features.
 225     Update minor on API changes.
 226     Update micro on API-compatible changes.
 227
 228 NOTES ON STARTING A NEW STABLE SERIES
 229 -------------------------------------
 230 - Given x.y.z being the last devel release, where y is an odd number
 231 - all API/ABI/renaming changes should be done
 232 - for every module:
 233   - get a completely fresh checkout
 234   - set GST_MAJORMINOR to x.(y + 1)
 235   - reset libtool versioning to 0, 0, 0
 236   - build every piece
 237   - grep for possible non-updates of MAJORMINOR:
 238     grep -r "0\.9" * | grep -v "0\.9\.6" | less -R
 239     change stuff:
 240     perl -i -p -e 's@0\.9(\.[^0-9])@0.10$1@g' (file) changes 0.9. -> 0.10.
 241     perl -i -p -e 's@0\.9([^.])@0.10$1@g' (file) changes 0.9 -> 0.10
 242
 243
 244
 245
 246