From 1d6fe234b44ff5a6347701e5919ee83373d3e4d7 Mon Sep 17 00:00:00 2001 From: Siggi Langauf Date: Wed, 17 Dec 2003 20:28:51 +0000 Subject: some release process documentation... CVS patchset: 5919 CVS date: 2003/12/17 20:28:51 --- doc/internal/HOWTO.release | 159 +++++++++++++++++++++++++++++++++++++++++++++ doc/internal/README | 6 ++ 2 files changed, 165 insertions(+) create mode 100644 doc/internal/HOWTO.release create mode 100644 doc/internal/README (limited to 'doc') diff --git a/doc/internal/HOWTO.release b/doc/internal/HOWTO.release new file mode 100644 index 000000000..6cd74b74e --- /dev/null +++ b/doc/internal/HOWTO.release @@ -0,0 +1,159 @@ +A step-by-step guide to xine releases +===================================== + +Siggi Langauf, 2003-12-17 + +This guide provides a simple "recipe-like" guide to making releases. While +only strictly covering releases of the "xine-lib" module, the procedure is +almost the same for all the other modules. You only have to substitute the +module name, and probably make other tests. ;-) + +Okay, so let's describe your starting point: +You're going to be the release manager. The last release has been a long +time ago. By now, many important bug fixes have accumulated in CVS while +users (who are not aware of any mailing list besides xine-announce) are +wondering if xine is still a maintained project. However, everybody's +committing wildly to CVS, preferrably redesigning the core xine engine and +often forgetting to make notes about their work in the ChangeLog. + +Currently, best practice to get a release out looks like this: + +1) announce the upcoming release on xine-devel! Ask developers: + - if they think CVS is ready for a release + - if there are any important known bugs + - to double-check and update the ChangeLog + +2) make pre-release checks (many of these should be already done, but now is + the time to go through the whole checklist: + - does it build? (probably best: check nightly build logs) + note: test at least on an ia32 machine _and_ any big endian box + - does it run? + (again: play a simple file on at least intel+any BE platform using the + new library) + - is it feature-complete? + Ideally, you'd test all demuxers, decoders and post plugins, along with + all audio and video drivers. As this is totally unrealistic, you'll + have to restrict yourself to a practical subset. This should include + the [standard test parcours] (see below) + note: We're going to collect all features in a strategical overview and + identify at least one dedicatet tester for each feature. + So check that overview! Ask testers to test if their feature is + marked "untested". + - does "make dist" produce a complete (ie. compilable) tarball + (note: nightly build logs will tell you this.) + +3) Versioning + + Make sure you know + - what the new release should be called + (the "marketing version" part of the tarball name, for example) + - if any _internal_ structures (like xine_t) have changed + - if any _external_ interfaces (include/xine.h) have been added or changed + + Then check our 3 version systems: + If any internal structures have changed, you may have to increase some + (or all) of the plugin IFACE_VERSIONs. In that case, you might want to + ask for help, so this doesn't take the whole day... + Then, edit configure.ac: + - set XINE_MAJOR, XINE_MINOR, XINE_SUB according to the marketing version + - set the LT_* constants according to the comments. DO _NOT_ mess with + these! If you're not sure about changed/added interfaces diff + include/xine.h against the previous release and/or ask! + +4) cvs commit your changes, and update CVS. Double-check CVS logs. Be sure + people have stopped comitting wildly. If they haven't: mail to xine-devel + and waitl till the dust settles! + +5) make a candidate tarball: + make maintainer-clean; rm .cvsversion; ./autogen.sh; make dist + (this is the time to make some tea, or better some strong coffee ;) + +6) check the candidate tarball: + - does it have the right name? + - does it unpack, compile and install correctly? + note: make sure to build with as many features as possible + on a Debian box, "apt-get build-dep xine-lib" and + "dpkg-buildpackage -rfakeroot" are a good way to do that + - test the candidate (and make sure you are running exactly the new + version!) This should at least cover the [standard test parcours] + + If you find any errors: fix them (get help on xine-devel or #xine) + and go back to step 4) + +The tests have now all passed. you've got the release tarball in your +hands. + +7) Tag the release: cvs tag -r xine-1_2_3-release + (this would be the tag for xine-lib-1.2.3, for example) + +8) upload the tarball to ftp:/upload.sf.net/incoming + note: you can start the upload while CVS is tagging + +9) Write release notes: Read through the ChangeLog, try to look at any + changes from a "what would users note" perspective: + - How would you classify the release (bugfixes, new features, ...)? + - Has anything visibly changed from previous releases? + - Are there any pitfalls/tricks for this upgrade? + - Which are the most obvious improvements? + Include the output of "md5sum xine-lib-1.2.3.tar.gz" in the release notes + and "gpg --clearsign" them. + +10) Click your way through the file release system on http://sf.net! + Copy&Paste both the (signed!) release notes and ChangeLog in there. + Make sure to check the "keep my preformatted text" box + +11) write the announcement for xine-announce: + You start with the release notes from step 9, without the signature, but + including the MD5 sum. rewrite it to look like an email announcing the + release. Copy&paste all ChangeLog entries for this release into the + announcement. Make sure you have GPG clearsigned the announcement when + sending it! + (also make sure it gets immediately approved by the aine-announce + moderator!) + +12) write the announcement for xinehq: + You need to login on xinehq and use your admin privileges to create a + news article in the "New Releases" section. Include a link to the + SourceForge Release notes/Changelog page and one to the download page. + + Warning: triple-check that you get the HTML correct! If you have + unmatched quotes, you might break the whole website so that it + can only be repaired by manually fiddling with mysql to get the + HTML right! + +13) write the Freshmeat announcement: + use your freshmeat account to log into their website, if you aren't + permanently logged in, anyway. + go to the xine project, click "add new release" and work your way + through. This announcement must be a bit more terse version of what you + wrote in step 9). And it should make people interested in the release. + +That's it. Finally. +At this point, you have probably earned your sleep ;-) + + + +The [standard test parcours] +---------------------------- + +There are a few things that simply _must_ work. So take a few minutes to +test at least: +- an MPEG1 video file +- a DivX AVI file (with AAC sound, + alternatively test _any_ file with AAC sound in addition) +- a DVD (test menu navigation, button highlighting, subtitles + and video playback) +- a VCD (preferrably with menu) +- an MP3 file, with goom visualization (does Ctrl+i overlay correct info?) +- a QuickTime or mp4 file + +For all those files, check: +- if audio/video are in sync +- video looks good +- audio sounds correct +- there is no visible jitter or stuttering +- try to seek a bit (more, yes, stress it!) + +If you find any anomalies: mail to xine-devel immediately! If you're lucky, +somebody will fix it before you're throught with the rest of your release +preparations. Asking on #xine may also help. diff --git a/doc/internal/README b/doc/internal/README new file mode 100644 index 000000000..323641351 --- /dev/null +++ b/doc/internal/README @@ -0,0 +1,6 @@ +This directory holds some documentation which is "internal to the xine +project". + +These files should not be distributed, not even with released tarballs, as +they are only useful in their most recent version, and only for a few core +developers who are supposed to have a CVS tree, anyway... \ No newline at end of file -- cgit v1.2.3