Version Control¶
serpentTools
uses git for version control. All the source
code can be found at https://github.com/CORE-GATECH-GROUP/serpent-tools.
Two main branches are provided: master
and develop
, and the
git flow branching
model is followed.
The master
branch should be considered stable and updated coincident with
each release.
The develop
branch is updated with more frequency as features are introduced.
This is the main branch of the project, and features should be introduced off
of this branch.
serpentTools
follows the semantic versioning
system, where the version number as found in setup.py
,
serpentTools/__init__.py
, and docs/conf.py
has the following form:
major.minor.patch
, e.g. 0.8.0
or 1.1.20
. Each of the numbers
should be incremented prior to new releases with the following designation:
Changes that are not backwards compatible should be denoted by incrementing the major number.
Changes that are backwards compatible and introduce sufficient new features to the API should be denoted by incrementing the minor number.
Changes that are largely internal and not recognizable by end-users should be denoted by incrementing the patch number
Note
Until a stable 1.0.0 release, the positions are essentially shifted,
e.g. the version is 0.major.minor
Releases¶
Following a release, the following actions should be performed:
Archived and installable python files should be created
Archived and installable python files should be uploaded to the python package index, PyPI
The tag should be pushed to GitHub and marked as a release, including information on the changes introduced in this release
This section details changes and procedures that, if followed, will increase chances of a painless release.
Updating the package version¶
Before and after a release, the project version number should be updated in the following places:
setup.py
serpentTools/__init__.py
docs/conf.py
The new version should be indicative of the changes introduced between this release and the previous release.
Generating distributions¶
The new distribution, that can be uploaded to PyPI, can be generated with
python setup.py sdist bdist_wheel
This will produce a source distribution and binary python wheel in the dist
directory, each of the form dist/serpentTools-<version>.<extension>
.
Before tagging and pushing releases to PyPI, the distribution should be
checked with
twine check dist/serpentTools-<version>*
twine will check that the package is compatible with the standards set by PyPI prior to uploading. Following a successful check, the distribution can be pushed to the package index using
..code:: sh
twine upload dist/serpentTools-<version>*
Tagging¶
Releases should be done with git tags from the master branch and then pushed to GitHub. Annotated tags should be used and can be created with
git tag -s <version>
Pushing these tags to GitHub creates a new release. If a message is used, the messages should be a brief message describing the changes on this tag. On the release page, a more detail list of changes, such as pull requests and issues closed, should be listed.
Commit Messages¶
When possible, please provide commit messages that:
have a initial single summary line (~<50 characters),
followed by a blank line,
followed by as detailed of a description as possible wrapped to ~70 characters wide
Helpful and detailed commit messages can make searching for changes easier and accelerate the review process. As an added benefit, if your pull request is a single commit, GitHub will automatically populate the request summary with your commit message!
Other references: