# 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.