pytokio Release Process¶
Branching process¶
General branching model¶
What are the principal development and release branches?
master
contains complete features but is not necessarily bug-freerc
contains stable code- Version branches (e.g.,
0.12
) contain code that is on track for release
Where to commit code?
- All features should land in
master
once they are complete and pass tests rc
should only receive merge or cherry-pick frommaster
, no other branches- Version branches should only receive merge or cherry-pick from
rc
, no other branches
How should commits flow between branches?
rc
should _never_ be merged back into master- Version branches should _never_ be merged into rc
- Hotfixes that cannot land in master (e.g., because a feature they fix no
longer exists) should go directly to the
rc
branch (if appropriate) and/or version branch.
General versioning guidelines¶
The authoritative version of pytokio is contained in tokio/__init__.py
and
nowhere else.
- The
master
branch should always be at least one minor number aboverc
- Both
master
andrc
branches should have versions suffixed with.devX
whereX
is an arbitrary integer - Only version branches (
0.11
,0.12
) should have versions that end inb1
,b2
, etc - Only version branches should have release versions (
0.11.0
)
Generally, the tip of a version branch should be one beta release ahead of what has actually been released so that subsequent patches automatically have a version reflecting a higher number than the last release.
Feature freezing¶
This is done by
- Merge master into rc
- In master, update version in
tokio/__init__.py
from0.N.0.devX
to0.(N+1).0.dev1
- Commit to master
Cutting a first beta release¶
- Create a branch from
rc
called0.N
- In that branch, update the version from
0.N.0.devX
to0.N.0b1
- Commit to
0.N
- Tag/release
v0.N.0b1
from GitHub’s UI from the0.N
branch - Update the version in
0.N
from0.N.0b1
to0.N.0b2
to prepare for a hypothetical next release - Commit to
0.N
Applying fixes to a beta release¶
- Merge changes into
master
if the fix still applies there. Commit changes torc
if the fix still applies there, or commit to the version branch otherwise. - Cherry-pick the changes into downstream branches (
rc
if committed tomaster
, version branch fromrc
)
Cutting a second beta release¶
- Tag the version (
git tag v0.N.0-beta2
) on the0.N
branch git push --tags
to send the new tag up to GitHub- Make sure the tag passes all tests in Travis
- Build the source tarball using the release process described in the Releasing pytokio section
- Release
v0.N.0-beta2
from GitHub’s UI and upload the tarball from the previous step - Update the version in
0.N
from0.N.0b2
to0.N.0b3
(orb4
, etc) to prepare for a hypothetical next release - Commit to
0.N
Releasing pytokio¶
Ensure that the tokio.__version__
(in tokio/__init__.py
) is correctly
set in the version branch from which you would like to cut a release.
Then edit setup.py
and set RELEASE = True
.
Build the source distribution:
python setup.py sdist
The resulting build should be in the dist/
subdirectory.
It is recommended that you do this all from within a minimal Docker environment for cleanliness.
Testing on Docker¶
Start a Docker image:
host$ docker run -it ubuntu bash
Use the Ubuntu docker image:
root@082cdfb246a1$ apt-get update
root@082cdfb246a1$ apt-get install git wget tzdata python-tk python-nose python-pip
Then download and install the release candidate’s sdist tarball:
host$ docker ps
...
host$ docker cp dist/pytokio-0.10.1b2.tar.gz 082cdfb246a1:root/
root@082cdfb246a1$ pip install pytokio-0.10.1b2.tar.gz
Then download the git repo and remove the package contents from it (we only want the tests):
root@082cdfb246a1$ git clone -b rc https://github.com/nersc/pytokio
root@082cdfb246a1$ cd pytokio
root@082cdfb246a1$ rm -rf tokio
Finally, run the tests to ensure that the install contained everything needed to pass the tests:
cd tests
./run_tests.sh
Travis should be doing most of this already; the main thing Travis does not do
is delete the tokio
library subdirectory to ensure that its contents are not
being relied upon by any tests.
Packaging pytokio¶
Create $HOME
/.pypirc with permissions 0600x
and contents:
[pypi]
username = <username>
password = <password>
Then do a standard sdist build
:
python setup.py sdist
and upload it to pypi:
twine upload -r testpypi dist/pytokio-0.10.1b2.tar.gz
and ensure that testpypi
is defined in .pypirc:
[testpypi]
repository = https://test.pypi.org/legacy/
username = <username>
password = <password>