How to Contribute

Everyone is welcome to contribute to the katcp-python project. If you don’t feel comfortable with writing core katcp we are looking for contributors to documentation or/and tests.

Another option is to report bugs, problems and new ideas as issues. Please be very detailed.

Workflow

A Git workflow with branches for each issue/feature is used.

  • There is no special policy regarding commit messages. The first line should be short (50 chars or less) and contain summary of all changes. Additional detail can be included after a blank line.
  • Pull requests are normally made to master branch. An exception is when hotfixing a release - in this case the merge target would be to the release branch.

reStructuredText and Sphinx

Documentation is written in reStructuredText and built with Sphinx - it’s easy to contribute. It also uses autodoc importing docstrings from the katcp package.

Source code standard

All code should be PEP8 compatible, with more details and exception described in our guidelines.

Note

The accepted policy is that your code cannot introduce more issues than it solves!

You can also use other tools for checking PEP8 compliance for your personal use. One good example of such a tool is Flake8 which combines PEP8 and PyFlakes. There are plugins for various IDEs so that you can use your favourite tool easily.

Releasing a new version

From time to time a new version is released. Anyone who wishes to see some features of the master branch released is free to request a new release. One of the maintainers can make the release. The basic steps required are as follows:

Pick a version number
  • Semantic version numbering is used: <major>.<minor>.<patch>
  • Small changes are done as patch releases. For these the version number should correspond the current development number since each release process finishes with a version bump.
  • Patch release example:
    • 0.6.3.devN (current master branch)
    • changes to 0.6.3 (the actual release)
    • changes to 0.6.4.dev0 (bump the patch version at the end of the release process)
Create an issue in Github

  • This is to inform the community that a release is planned.

  • Use a checklist similar to the one below:

    Task list:
    - [ ] Read steps in the How to Contribute docs for making a release
    - [ ] Edit the changelog and release notes files
    - [ ] Make sure Jenkins tests are still passing on master branch
    - [ ] Make sure the documentation is updated for master (readthedocs)
    - [ ] Create a release tag on GitHub, from master branch
    - [ ] Make sure the documentation is updated for release (readthedocs)
    - [ ] Upload the new version to PyPI
    - [ ] Fill the release description on GitHub
    - [ ] Close this issue

  • A check list is this form on github can be ticked off as the work progresses.

Make a branch from master to prepare the release
  • Example branch name: user/ajoubert/prepare-v0.6.3.
  • Edit the CHANGELOG and release notes (in docs/releasenotes.rst). Include all pull requests since the previous release.
  • Create a pull request to get these changes reviewed before proceeding.
Make sure Jenkins is OK on master branch
  • All tests on Jenkins must be passing. If not, bad luck - you’ll have to fix it first, and go back a few steps…
Make sure the documentation is ok on master
Create a release tag on GitHub
  • On the Releases page, use “Draft a new release”.
  • Tag must match the format of previous tags, e.g. v0.6.3.
  • Target must be the master branch.
Make sure the documentation is updated for the newly tagged release
Upload the new version to PyPI
  • Log in to https://pypi.org.
  • Get account permissions for katcp from another contributor, if necessary.
  • If necessary, pip install twine: https://pypi.org/project/twine/
  • Build update from the tagged commit:
    • $ git clean -xfd  # Warning - remove all non-versioned files and directories
    • $ git fetch
    • $ git checkout v0.6.3
    • $ python setup.py sdist bdist_wheel
    • $ python3 setup.py bdist_wheel
  • Upload to testpypi, and make sure all is well:
    • $ twine upload -r testpypi dist/katcp-0.6.3.tar.gz
    • $ twine upload -r testpypi dist/katcp-0.6.3-py2-none-any.whl
    • $ twine upload -r testpypi dist/katcp-0.6.3-py3-none-any.whl
  • Test installation (in a virtualenv):
    • $ pip install katcp
    • $ pip install -U -i https://test.pypi.org/simple/ katcp
  • Upload the source tarball and wheel to the real PyPI:
    • $ twine upload dist/katcp-0.6.3.tar.gz
    • $ twine upload dist/katcp-0.6.3-py2-none-any.whl
    • $ twine upload dist/katcp-0.6.3-py3-none-any.whl
Fill in the release description on GitHub
  • Content must be the same as the details in the changelog.
Close off release issue in Github
  • All the items on the check list should be ticked off by now.
  • Close the issue.