- You have a working knowledge of how to use a virtualenv.
- You have shell access to the turbogears site.
- You know how to run the
nosetests
on your local git clones of TurboGears.- You have to have a working knowledge of git, and how to do merging and branching.
- 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.
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:
- Repository Branching
- Finalizing Changes On ‘next’ Branch
- Preparing Changelog And Release Announcement
- Preparing Packages And The Documentation
- Uploading The Documentation
- Pushing to PyPI
- Publishing Release Annoucement And Closing Milestones
- Final Cleanup
Below, we discuss each of these steps in detail.
We have three main repositories: TG2, TG2Devtools, and TG2Docs. Each of them functions in a similar fashion for this process:
- Clone the repository
- Checkout the “development” branch and update it
- 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.
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.
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.
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).
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.
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.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.
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
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.
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.