Webware for Python - Release Procedures

Preface

These notes have expanded and changed upon every release. Carefully
consider each step as you make it. Look for opportunities to improve.
Also, update these notes immediately following a release.

To Do

Check whether there are outstanding issues which should be
finished before the release:

[ ] Announce the timing for the release on the webware-devel mailing list.

[ ] Browse through the tracking systems on the Webware project page
    at SourceForge. There are tracking systems for "Bugs", "Patches"
    and "RFE". The SourceForge task manager is currently not used.

[ ] Search for @@ (to do) markers in the code and docs.

[ ] Browse through WebKit/Docs/Future.html

Testing

Test the current version before releasing it:

[ ] Run install.py and check that the installation runs properly.

[ ] Run all unittests using AllTests.py.

[ ] Run other standalone Python test suites
    not included in AllTests.py (this needs to be better documented).
    > cd SomeKit/Tests
    > python Test.py

[ ] Run the WebKit AppServer and check that the default contexts
    (Admin, Examples, Docs etc.) are working. Also check the various
    tests in the Testing context.

[ ] Make sure that mod_webkit and all other important components can
    be compiled, linked and used without problems.

Prepare the trunk

[ ] Make sure the workspace is up to date.

[ ] Update the release notes:
    * Search webware-discuss and webware-devel archives for "update"
      in the subject, since the date of the last release.
    * Browse the subversion log messages, starting with the date
      of the last release.

[ ] Update the HTML pages that are created from reStructuredText
    (currently these exist only in the folder WebKit/Docs).
    * Docutils (0.3.9) must be installed
      (that's why this is not done in the Webware installer)
    * Copy buildhtml.py from the Docutils tools directory
      somewhere to the PATH
    > cd WebKit/Docs
    > buildhtml.py --stylesheet=../../Docs/Doc.css
    * check the produced HTML pages
    The installer will modify these HTML pages later to display the
    same header and footer as the other HTML pages.

[ ] Make sure there are no empty directories or zero length files
    (such as __init__.py). Old unarchivers often ignore these, leading
    to problems for users. The following command can be used for this:
    > find . -name '.svn' -prune -o -empty -print

[ ] Skim through docs and release notes one final time.

[ ] Commit all changes in the workspace.

Tag the release

[ ] Choose an appropriate version number for the release.
    Releases often go alpha 1, alpha 2, beta 1, beta 2,
    release candidate 1, release candidate 2, ...
    with suffixes a1, a2, b1, b2, rc1, rc2 as in 0.6.1b2.

[ ] Tag the version in the SVN repository.
    The tag name should be "Release-VER", with underscores instead
    of dots in VER. Look at the existing tags to make sure your
    new tag is of a suitable style.
    The command for creating the tag would be like this:
    > svn copy http://svn.w4py.org/Webware/trunk \
        http://svn.w4py.org/Webware/tags/Release-0_9b3 \
        -m "Tagging version 0.9 beta 3 of Webware for Python."

[ ] Switch your working copy to the newly created tag:
    > svn switch http://svn.w4py.org/Webware/tags/Release-VER

[ ] Update all version numbers using bin/serversion.py:
    * Edit bin/setversion.py and set the following parameters:
      - version = the version number of this release
      - releaseDate = the release date
      - setVersion = True
      - newRelease = False
    * Run bin/setversion.py - this will change the version in the
      Properties.py files and the .txt and .html doc files, and it will
      rename ReleaseNotes-X.Y.phtml according to the version set above.
    * Make sure all the version numbers and release dates have been set
      properly, particularly in the Properties.py files.
      The .phtml doc files will be converted to .html at install time
      and take the version number from the Properties.py files.

[ ] Update the HTML pages that are created from reStructuredText.
    This must be done to reflect the version number in the HTML pages after
    it has been set in the preceding step. See above for this procedure.

[ ] Commit these changes on the workspace to the tag in the repository.
    Your SVN client may warn you to do so on a tag path, ignore this.
    From then on, the tag in the repository should not be touched any more
    (this should be really a tag only, not a branch).

Create the tarball to be released

Note: This must be done on Unix. Otherwise, Posix permissions may get
lost and you may get problems with wrong EOL characters.

[ ] Use ReleaseHelper to create the release. This performs a SVN
    export of the repository to create a directory without the SVN
    control files, and then builds a tarball from that directory.
    For instance, for creating the 0.9 beta 3 tarball:

    > bin/ReleaseHelper.py tag=Release-0_9b3

    If you specify the tag name, the tarball is built using the revision
    information found in the release. Otherwise the tarball is built
    and named with the current date indicating a snapshot build.
    See the docstring and code of ReleaseHelper for the details.

    Following these procedures assures that the SVN tagged version
    is what is actually in the released tarball.

Test the released tarball

Test the released tarball, preferably under Unix and also under Windows.
[ ] Install Webware from the released tarball.

[ ] Check that the right versions show up in the WebKit examples and
    in the documentation.

[ ] Perform some more testing as above to make sure all needed
    files exist in the release and permissions are set properly.

Publish the released tarball

[ ] Publish for download from the SourceForge files section:

    > ncftpput -V upload.sf.net /incoming Webware-VER.tar.gz

    * Log into sf.net.
    * Go to the Webware Project Page
      at SourceForge.
    * Click 'Admin' in the top menu bar.
    * Click 'File Releases' in the second menu bar.
    * Proceed to completion, but don't send users notification of
      release until final test is performed and the web site is updated.
    * Reference for the above: "Guide to the SourceForge FRS"
    * Download the release from SourceForge and test again.
    * Review the trove categorization and update if necessary
      - Click 'Admin' in the top menu bar.
      - Click 'Public Info' in the second menu bar.
      - Click 'Edit Trove Categorization'.

[ ] Publish for download from the www.w4py.org web server:

    > scp Webware-VER.tar.gz www.w4py.org/var/www/downloads/Webware

    * Check that this can be downloaded from www.w4py.org/downloads/

Update Home Page

[ ] Update webware.sf.net:

    * Updates to that home page should go through CVS at SourceForge.
      In general you should not be editing files directly on the HomePage
      site because that site only has read-only access to CVS.

    * Note that the webware.sf.net home page is not really used any more.
      The index page is redirected via .htaccess to www.w4py.org
      (nevertheless, the site is still available and can still be
      accessed as http://webware.sourceforge.net/oldsite/).
      So you can skip the following step.

    * Update your own copy of the HomePage:
      * Checkout the current version:
        > cvs co HomePage
      * Update:
        * Last updated (at top of page)
        * Version number, including links
        * File size
        * Project status
        * Testimonials
      * Review all text and links
      * Checkin the updated version:
        > cvs ci

    * We should still copy and install Webware in the webware.sf.net
      web page directory so the documentation can be browsed online there.
      Make sure you install this from the tarball.

    * Copy the tarball to your SourceForge account.
      > scp Webware-VER.tar.gz $USER@webware.sf.net:

    * Login to the SourceForge account.
      > ssh $USER@webware.sf.net

    * Extract the Webware folder and create a symbolic link to it:
      > cd /home/groups/w/we/webware/htdocs/
      > rm -rf Webware
      > tar -xzf ~/Webware-VER.tar.gz
      > ln -s Webware-VER Webware
      > cd Webware
      > ./install.py
      > chmod -R g+w .

    * Since you probably did not make changes to the home page
      through CVS, you can skip the following step again:

    * Update the HomePage on SourceForge from CVS.
      > cvs -q up -dP

    * Yerify that the home page changes are correct by browsing to
      Webware.sf.net and double-checking
      all of the updated links, including the download link.
      Also check Webware.sf.net/Webware/Docs/.

    * Add a news item to the Webware Project Page at SourceForge

[ ] Update www.w4py.org:

    * Updates to the home page should go through SVN at svn.w4py.org,
      again located in the toplevel directory HomePage.
      This is a Webware working directory with the default context 'Home'.
      Webware is installed in /usr/local/share/Webware.
      This should always be the last stable release,
      so you may have to update it with the current release.
      You may also have to recreate the working directory and
      the start scripts if there are major changes in the release.

    * The download link at the top right corner is in SitePage.py.

    * All contexts except the default 'Home' and 'Docs' contexts should be
      disabled in Application.config.

    * The content of the home page is stored in the Webware Wiki
      and can be updated via the browser. You should update it
      and add an announcement for the new release.

Notify

[ ] Create a new announcement text file containing the text for the
    general announcement, SourceForge news and freshmeat.net update.
    Use the previous releases as examples.

    For pre-releases, just the following:
      * To: webware-discuss@lists.sf.net
      * http://prdownloads.sf.net/webware/Webware-VER.tar.gz
      * Report all problems to webware-discuss@lists.sf.net.
        Please include all appropriate version numbers including Webware,
        Python, web server, op sys, browser, database, etc. If running
        the app server, please specify flavor (eg, ThreadedAppServer)
        and adapter.
      * Expected release date for X.Y is MONTH, DAY.
      * Changes since last release date are:
        * ...

Announce on mailing lists:
    [ ] python-list@python.org
    [ ] python-announce@python.org
    [ ] webware-announce@lists.sf.net
    [ ] pywx-announce@lists.sf.net
    [ ] db-sig@python.org
        - Only if MiddleKit was updated
        - Make custom message focused on MiddleKit

Update:
    [ ] Web Programming in Python
    [ ] Vaults of Parnassus
    [ ] freshmeat.net

[ ] Review/search for other places where the announcement can be made.

Post-release

[ ] Update these Release Procedures.

[ ] If this was a final release, archive the release notes and create new
    templates for the release notes in preparation of the next release:
    * Edit bin/setversion.py and set the following parameters:
      - version = the version number of this release
      - releaseDate = the release date
      - setVersion = False
      - newRelease = True
    * Run bin/setversion.py - this will not change the version in the
      Properties.py files and the .txt and .html doc files, but it will
      rename ReleaseNotes-X.Y.phtml according to the version set above
      and copy new templates for these files instead.
    * Make sure the release notes have been copied properly.

[ ] Check that the following were updated:
    [ ] Vaults of Parnassus
    [ ] freshmeat.net

[ ] Look for follow up messages on comp.lang.python

[ ] Test drive the home page, project page and download.

[ ] Check the download counter and activity statistics on SourceForge.