Creating Tangelo Releases¶
Tangelo is developed on GitHub using the Git Flow work style. The
main development branch is named
develop, while all commits on
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
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
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
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
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,
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:
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
upload option to
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
develop to thread through the release branch to simplify
the graph view of the release. After the next step, this leaves both
develop one commit ahead of the same, prepared release branch point.
11. Bump the version number again. The version number on the
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
once more, as well as
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
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
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 tangelowill install the new version to the system.
- a new, tagged commit on
masterthat 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 via
- a new commit on
developrepresenting a starting point for further development. Be sure to create topic branches off of
developto implement new features and bugfixes.
- documentation for the new version, live on Read The Docs.