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