# Preparing a Release of TurboGears

## Prerequisites

> 1. You have a working knowledge of how to use a virtualenv.
> 2. You have shell access to the turbogears site.
> 3. You know how to run the `nosetests` on your local git clones of TurboGears.
> 4. You have to have a working knowledge of git, and how to do merging and branching.
> 5. You need permission to update the TurboGears2 and tg.devtools packages on PyPI

With those prerequisites in mind, this document will not cover all the command lines that you could run. Instead, we will specify steps as “activate your virtualenv” or “run nosetests” or the like.

## Summary of Steps

Preparing a release of TurboGears is going to take some time and effort. It is unlikely to be completed in a mere day or two, so please plan on taking some time to work through it all.

The steps for the release, in summary, are as follows:

> 1. Repository Branching
> 2. Finalizing Changes On ‘next’ Branch
> 3. Preparing Changelog And Release Announcement
> 4. Preparing Packages And The Documentation
> 5. Uploading The Documentation
> 6. Pushing to PyPI
> 7. Publishing Release Annoucement And Closing Milestones
> 8. Final Cleanup

Below, we discuss each of these steps in detail.

## Repository Branching

We have three main repositories: TG2, TG2Devtools, and TG2Docs. Each of them functions in a similar fashion for this process:

> 1. Clone the repository
> 2. Checkout the “development” branch and update it
> 3. Checkout the “next” branch and merge development into it

Once the “next” branch is made, this is where you will do all work until the release is done.

## Finalizing Changes On ‘next’ Branch

After all the changes that you’ve made so far, the final changes are simply to get the new version numbers into the distributed files.

> - In TG2:
>   - Update tg/release.py to have the new version number.
> - In TG2Devtools:
>   - Update setup.py:
>     - Update the version number
>     - Update the install requirements so that it requires TurboGears2 >= the new version number
>   - Update devtools/templates/turbogears/setup.py_tmpl:
>     - Update the install requirements so that it requires TurboGears2 >= the new version number
>   - Update CHANGES.txt:
>     - Add new release with changelog generate with: `git log --no-merges --format="* %s" LAS_RELEASE_TAG..HEAD` (LAST_RELEASE_TAG is the tag of the previous release, like tg2.3.2). Please take only meaningful changes.
> - In TG2Docs:
>   - Update requirements.txt:
>     - Change TurboGears dependency line from `@development` to current release (EX: `@tg2.3.2`).
>   - Update docs/confg.py:
>     - Update the version number

Commit all of these changes, but do not push them public, not yet.

## Preparing Changelog And Release Announcement

For each of the three repositories, you will need to review the commit logs since the last release. Gather up the summaries for each one, and prepare a new file. Use the standard GNU Changelog format. However, instead of recording individual file changes, record only the summaries. We don’t need the file changes since Git records those changes for us.

Review the GitHub tickets for this milestone, and record any tickets that were closed for this repository but were not referenced in the summaries you’ve already recorded.

The changelog files you’ve made will be the commit message for the tags you are about to make.

In addition, prepare a release announcement. Anything I can say here sounds condescending. You should prepare it, though, so that as soon as you reach the “Publish” step, it’s all done in a few minutes.

## Preparing Packages And The Documentation

First, merge the branch “next” onto the branch “master”. Then, tag the master branch with the new version number, and use the changelog you’ve generated as the commit message. The tag should be an annotated tag (i.e.: `git tag -a"`).

Do this for each of the three repositories.

For the documentation, go into the appropriate directory, and type `make html` (either the docs or the book, whichever is needed to be uploaded).

## Uploading The Documentation

When you run `make html`, it will create a directory “_build/html”. Upload the contents of that directory and replace the current directory with it. For instance, if you used rsync to upload to your user account on the server, and fixed the permissions so that the website user could read the files, you could then do `rsync -avP --delete /path/to/new/docs /path/to/web/docs/directory` and have everything properly uploaded/visible to the users.

Do not forget the book! Enter the tg2docs/book folder, and run
  `make html`. This will produce the necessary html files for the book. Upload the contents of the book/_build/html directory to the webserver. Use similar commands as were used for copying the older html docs to complete the process.

## Making The Source Distribution For The New Eggbasket

At this point, everything is prepared, with one exception: The source distributions for TurboGears2 and tg.devtools must be placed in the eggbasket. Enter your local repository directory for both `TG2.x Core` and `TG2.x DevTools` and run `python setup.py sdist`. In both of them, you will produce a directory named `dist` with a .tar.gz file for the new version. Copy these files to your `${HOME}/eggbasket`, then go to `${HOME}/eggbasket` and run `makeindex *`.

Using the steps in `Testing Jenkins With The Upgraded Packages And Code`, upload the updated (and finalized) eggbasket to the turbogears.org web server.

## Making The New Eggbasket The Current On Turbogears.org

Log in to the turbogears website. Go into the directory where you stored the “next” directory, and rename “next” to the version you are releasing. Remove the “current” link, and then do a symbolic link from the version being released to “current”, like so: `ln -s 2.1.1 current`

## Pushing to PyPI

For all three repositories, do `python setup.py upload`.

## Publishing Release Annoucement And Closing Milestones

Publish your release announcement to the places of your choice. We recommend your blog(s) and twitter. In addition, update the turbogears “Current Status” page to reflect the new release.

## Final Cleanup

For each of the three repositories, merge the “master” branch to the “development” branch.

You’re done. Sit back and enjoy having accomplished a release.