# 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

    [ ] Check for compliance with Docs/StyleGuidelines.html by running
        bin/checksrc.py or using pylint with PYLINTRC=/path/to/Webware/.pylintrc

## Testing

    Test the current version before releasing it:

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

    [ ] Run all unittests using AllTests.py. Don't forget to activate the MySQL
        tests in AllTests.config and check that these are running as well.

    [ ] Run other standalone Python test suites not included in AllTests.py.
        > cd SomeKit/Tests
        > python Test.py
        See MiddleKit/Tests/ReadMe.text for more information on MiddleKit tests.

    [ ] Run the WebKit AppServer and check that the default contexts
        (Admin, Examples, Docs etc.) are working.

    [ ] Check that all links in the Docs context are working.

    [ ] Check the various tests in the Testing context.

    [ ] Run some stress tests using the tool in WebKit/Tests/stress
        (check with different parameters, particularly setting slowconn=1).

    [ ] Run the twill test scripts in WebKit/Tests/twill.

    [ ] Make sure that wkcgi, mod_webkit1, mod_webkit2, and all other important
        adapters can be compiled, linked and used without problems. If there have
        been changes, provide binaries for Windows users and adjust the version
        number in mod_webkit.c to the Webware version.

    [ ] Run the above tests on all supported Python versions (currently 2.0-2.6)
        and different platforms (e.g. various flavors of Linux, MacOS, Windows).

## 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.
        * Remove all empty subsections in the release notes. Remove subtitles
          if there is only one category.

    [ ] Update the HTML pages that are created from reStructuredText
        (currently these exist only in the folder WebKit/Docs).
        * Docutils 0.5 must be installed. (Since we don't want Webware to depend
          on Docutils, the HTML pages come shipped with the Webware package, and
          are not created by the Webware installer.)
        * Run the following commands:
          cd WebKit/Docs
          python ../../DocSupport/buildhtml.py
        * check the produced HTML pages
        The installer will later modify these HTML pages 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/setversion.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.

        Using the option pkg=zip, you can also build a zip archive instead
        of the tarball that will make the MS Windows users happy.

## 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:
        * Upload Webware-VER.tar.gz to SourceForge.
          - Note that FTP upload is not supported any more.
          - You can use the Web upload page, for example.
        * Log into sf.net.
        * Go to the Webware Project Page at SourceForge.
        * Select 'File Releases' from the 'Admin' tab menu.
        * Click on 'Manage Packages/Releases'.
        * Choose the 'Webware' package for releases only, and use the
          'Webware-devel' package for betas and release candidates.
        * Proceed to completion, but don't send users notification of
          release until final test is performed and the web site is updated.
        * Make this the primary file for download with 'Edit Download Page'.
        * Hide older releases and candidates that aren't of interest any more.
        * Reference for the above: "Guide to the SourceForge FRS"
        * Review the trove categorization and update if necessary:
          - Select 'Public Info' from the 'Admin' tab menu.
          - Click 'Edit Trove Categorization'.
        * Download the release from SourceForge and check that the downloaded
          file is identical with the one we have tested and uploaded.

    [ ] 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 --set-password=""
          > 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

        * Verify 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
            (or post to comp.lang.python)
        [ ] python-announce@python.org
            (or post to comp.lang.python.announce)
        [ ] webware-announce@lists.sf.net
        [ ] db-sig@python.org
            - Only if MiddleKit was updated
            - Make custom message focused on MiddleKit

    Update:
        [ ] Web Programming in Python
        [ ] PyPI (aka "Cheese Shop")
        [ ] Vaults of Parnassus (currently out of order)
        [ ] 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 (currently out of order)
        [ ] 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.