Webware for Python - Release Procedures


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 tickets on the Webware project page
    at SourceForge. We have ticket categories for "Bugs", "Patches"
    and "Feature Requests".

[ ] Browse through the issues on the Webware project page
    at GitHub.

[ ] 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


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.
    > cd SomeKit/Tests
    > python Test.py
    See MiddleKit/Tests/README 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 these are
    Python versions 2.6 and 2.7 and also PyPy) and on different platforms (e.g.
    various flavors of Linux, MacOS, Windows).

Prepare the master branch

[ ] 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 git 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.13 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 '.git' -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.

[ ] Create a branch for the version in the Git repository
    and switch to this branch. The branch name should be the
    same as the version number.
    The command for creating the branch would be like:
    > git checkout -b release-1.2.1

[ ] 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 branch in the repository
    and create an annotated tag for the release.
    The commands for committing and creating the tag would be like:
    > git commit -m "Release Webware for Python 1.2.1"
    > git tag -a 1.2.1 -m "Webware for Python version 1.2.1"

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 extracts all necessary
    files from the repository to create a directory without the Git
    repository itself, and then builds a tarball from that directory.
    For instance, for creating the 1.1.2 tarball:

    > bin/ReleaseHelper.py tag=1.1.2

    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 tagged version in the
    repository 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:
    * Go to the Webware Project page
      at SourceForge and log in with your developer account.
    * Select 'Files' from the menu bar.
    * Create a folder for the new release and upload the .tar.gz and .zip files
      using the web interface.
    * Click the info button next to the uploaded files and set these files
      as default downloads for Windows (.zip) and all others (.tar.gz).
    * Review the trove categorization and update if necessary:
      - Select 'Project settings' from the 'Project Admin' 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.

Update Home Page

[ ] Update webware.sourceforge.net:

    * Note that the webware.sourceforge.net home page is not really used any more.
      The index page is redirected via .htaccess to cito.github.io/w4py/.

    * We should still copy and install Webware in the webware.sourceforge.net
      web page directory so that the documentation can be browsed online there
      for Webware versions that do not yet use Sphinx.
      Make sure you install this from the tarball.

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

    * Login to the SourceForge account.
      > ssh -t $USER,webware@shell.sourceforge.net create

    * Extract the Webware folder and create a symbolic link to it:
      > cd /home/project-web/webware/htdocs/
      > rm Webware
      > tar -xzf ~/Webware-VER.tar.gz
      > ln -s Webware-VER Webware
      > cd Webware
      > ./install.py --set-password=""

    * Check webware.sourceforge.net/Webware/Docs/.

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

[ ] Update cito.github.io/w4py/:

    * Updates to the home page should go through the gh-pages branch of the
      GitHub repository.


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

    For pre-releases, just the following:
      * To: webware-discuss@lists.sourceforge.net
      * https://sourceforge.net/projects/webware/files/Webware/VER/Webware-VER.tar.gz
      * Report all problems to webware-discuss@lists.lists.sourceforge.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 (e.g. 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.sourceforge.net
    [ ] db-sig@python.org
        - Only if MiddleKit was updated
        - Make custom message focused on MiddleKit

    [ ] Web Frameworks for Python
    [ ] Python Package Index (PyPI)

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


[ ] 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.
    * Commit the changes to the master branch.

[ ] Look for follow up messages with feedback and bug reports on the mailing lists.

[ ] Check the GitHub, SourceForge and the PyPI pages.