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