Versioning
For better managing and releasing code, here is a summary about the versioning story of ElasticDL. Some previous discussions can be found here.
Branches
There are three different type branches:
- develop branch: the main branch where the source code always reflects a state with the latest delivered development changes for the next release.
- feature branches: branch off from the
develop
branch and merge back intodevelop
.Feature
branches are used to develop new features, and created/maintained by developers themselves.Feature
branches will be deleted after code changes get merge infodevelop
branch. - release branches: branch off from the
develop
branch. When thedevelop
branch reaches the desired state of a new release, cut off a new release branch, and start to publish new versions there. Release branches will be kept.
For version numbers, we follow the Semantic Versioning
2.0.0 with style MAJOR.MINOR.PATCH (e.g. 0.2.1). For each
MAJOR.MINOR, we keep a corresponding release
branch (named branch-x.y
), and
each following patch version x.y.z is released from it.
Feature Development
New features and bugfixes are developed in feature
branches. Make sure you
work with the latest version of develop
branch.
# Start a new feature branch from develop branch
$ git checkout -b feature1 develop
# Do some code changes locally
$ git commit -a -m "Add some feature description"
$ git push origin feature1
# Create a PR for feature1 in https://github.com/sql-machine-learning/elasticdl
# Once the PR gets accepted and merged, it is ok to delete the branch locally
$ git checkout develop
$ git branch -D feature1
Here is the tutorial on how to open a pull request.
Releasing
Here are detailed steps for releasing an example version 0.1.0.
# Update RELEASE to include the new changes and get merged in develop branch
# Then, start a new release branch from develop branch
$ git checkout -b branch-0.1 develop
$ git push origin branch-0.1
# Prepare the first release candidate version v0.1.0rc0
$ ./scripts/bump_version.sh v0.1.0rc0
# Then commit changes
$ git commit -a -m "Release v0.1.0rc0"
$ git push origin branch-0.1
# Publish v0.1.0rc0 to PyPI
# A detailed instruction is available at https://packaging.python.org/tutorials/packaging-projects/
So now we have v0.1.0rc0 ready to use. Test out this version. If any issues
found, get them fixed in develop
branch, merged into branch-0.1
branch, and
repeat the aforementioned steps to publish a new release candidate version. We
keep releasing rc
version until no further issues found. At that time, release
the official v0.1.0
version.
$ git checkout -b branch-0.1 develop
$ ./scripts/bump_version.sh v0.1.0
# Also remember to update RELEASE
$ git commit -a -m "Release v0.1.0"
$ git push origin branch-0.1
# Publish v0.1.0 to PyPI
# Also add a tag for this release
$ git tag v0.1.0 -a
$ git push origin v0.1.0
Note that for creating new releases and tags, you can also do from the website.
For cases where the release
branch already exists (for example when releasing
0.1.1 and branch-0.1
is already there), just reuse that release
branch and
merge required commits from develop
branch to the corresponding release
branch.