Tangelo is developed on GitHub using the Git Flow work style. The
main development branch is named develop
, while all commits on master
correspond to tagged releases. Topic, hotfix, and release branches are all used
as described in the discussion in the link above.
This page documents the careful steps to take in creating a new release, meaning
that a new commit is made on master
, and a package is uploaded to the Python
Package Index.
Suppose for the sake of example that the last release's version number is 1.1. The following procedure will produce a new release of Tangelo:
1. Merge all topic branches to develop. Be sure that develop
contains
the code from which you wish to create the new release.
2. Create a release branch. A release branch needs to be created off of develop:
git checkout -b release-1.2 develop
Note that the version number mentioned in the branch name is the version number of the release being created.
3. Bump the version number. Edit the file package.json
in the top level
of the repository, updating the version number to 1.2.0. Be sure to use the
major.minor.patch format.
Also edit js/tests/tangelo-version.js
, tests/tangelo-version.py
, and
tests/commandline-version.py
to bump the version numbers there manually (in
each file, the expected version string is contained in a variable named
expected
). This is done by hand to ensure that the version tests are
deployed correctly for step 6 below.
Finally, edit the file CHANGELOG.md
in the root of the codebase. Change the
[Unreleased] - [unreleased]
line near the top of the file to something like
[1.2.0] - 2014-12-18
. Look over the specified changes. Edit these if
necessary, making sure that the list is up to date.
4. Build Tangelo. Issue the following commands to create a fresh build of Tangelo from scratch:
grunt clean:all
npm install
grunt
This should result in a virtual environment with a newly built Tangelo. Bumping the version number in the previous step means that Grunt should have also updated the version string in all parts of the code that require it.
5. Commit. Make a commit on the release branch containing the version number update:
git commit -am "Bumping version number for release"
then launch Tangelo with
./venv/bin/tangelo --examples
and visit http://localhost:8080/plugin/tangelo/version to verify the version
number there. Finally, load up any of the examples that uses tangelo.js
(e.g., http://localhost:8080/plugin/vis/examples/barchart), and, in the console,
issue tangelo.version()
to verify the clientside version number as well.
6. Run the tests.
Issue this command to verify that the client and server side tests all pass:
grunt test
If any tests fail, fix the root causes, making commits and retesting as you go. In particular, the tests regarding Tangelo version numbers will fail if the version number bump or build process did not work properly for any reason.
7. Merge into master. Switch to the master
branch and merge the release
branch into it:
git checkout master
git merge --no-ff release-1.2
Do not omit the --no-ff
flag! You can use the default merge commit message.
If you run into merge conflicts, carefully fix them and conclude the merge, then make sure to run the tests again.
8. Tag the release. Create a tag for the release as follows:
git tag -a v1.2
Use a commit message like "Release v1.2". Be sure to push the tag so it becomes visible to GitHub:
git push --tags
9. Upload the package to PyPI. Unpack the built package file, and then use
the upload
option to setup.py
:
cd sdist
tar xzvf tangelo-1.2.0.tar.gz
../venv/bin/python setup.py sdist upload
10. Merge into develop. The changes made on the release branch must be
merged back into develop
as well, so that development may continue there:
git checkout develop
git merge release-1.2
This is one of the few times you should not use the --no-ff
flag. We want
both master
and develop
to thread through the release branch to simplify
the graph view of the release. After the next step, this leaves both master
and develop
one commit ahead of the same, prepared release branch point.
11. Bump the version number again. The version number on the develop
branch needs to be changed again, to add a -dev suffix. In our example, the
version number will now be 1.2.0-dev. This entails editing package.json
once more, as well as js/tests/tangelo-version.js
,
tests/tangelo-version.py
, and tests/commandline-version.py
.
Also edit CHANGELOG.md
again, reproducing a skeleton of a new changes
section, copying the following:
## [Unreleased] - [unreleased] ### Added ### Changed ### Deprecated ### Removed ### Fixed ### Security
This will allow developers to update the appropriate section easily whenever a
topic branch is merged to develop
.
12. Test again. Run the tests one more time, to verify that the version number bump happened correctly, and to catch anything weird that may have happened as well.
13. Commit. Commit the change so that develop
is ready to go:
git commit -am "Bumping version number"
14. Push. Push both develop
and master
to origin to bring the local
and remote branches up to date.
15. Update the documentation. Log into https://readthedocs.org, go to the Tangelo documentation panel, go to the "version" link, and activate the documentation for v1.2. Log out and verify that the new documentation appears at https://tangelo.readthedocs.org.
You now have
- a new Tangelo package on PyPI. Installing with
pip install tangelo
will install the new version to the system. - a new, tagged commit on
master
that corresponds exactly to the new release, and the new package in PyPI. Anyone who checks this out and builds it will have the same Tangelo they would have if installing viapip
as above. - a new commit on
develop
representing a starting point for further development. Be sure to create topic branches off ofdevelop
to implement new features and bugfixes. - documentation for the new version, live on Read The Docs.