Development

Python Wires is openly developed on GitHub, following a process that strives to be:

• As simple as possible, but not simpler.
• Easy to understand.
• Structured.
• Flexible.

Substantiated contributions to its improvement and related discussions will be welcome.

Environment

Setting up a development environment should be done under a Python virtual environment:

$ git clone https://github.com/tmontes/python-wires
$ cd python-wires/
$ pip install -e .[dev]

Running the test suite:

$ python -m unittest discover

Running the test suite with code coverage and branch reporting:

$ coverage run --branch -m unittest discover
$ coverage report

Building the documentation, which will be available under docs/build/html/:

$ cd docs && make html

Running the test suite with tox:

$ pip install tox tox-venv
$ tox

Process

GitHub Issues, Labels, Milestones, and Pull Requests are used to track Python Wires development.

• Issues must be labelled and associated to a milestone.
• Pull Requests must reference, at least, one issue (and preferably only one).
• Pull Requests will not be merged if any of the GitHub checks fails.
• Pull Requests will not necessarily be merged if all of the GitHub checks pass.

Milestones

The following GitHub Milestones are tracked:

NEXT	Issues and Pull Requests that will be included in the next release.
DEFER	Issues and Pull Requests that will be worked on, but will not be included in the next release.
TBD	Issues and Pull Requests that will not be worked on until future decision.

Note

Unassigned Issues and Pull Requests will be assigned to the TBD milestone.

At release time:

• The NEXT milestone is renamed to the release version and closed.
• A new NEXT milestone is created, with no associated Issues or Pull Requests.

Issues and Labels

All development issues will be labelled one of:

enhancement	Describing a new feature or capability.
bug	Describing something that isn’t working as documented.
release	Describing release process issues.
maintenance	Describing other development related issues: refactors, automation, process, etc.

Note

The key motivation for having mandatory labels in development issues is to simplify filtering support related ones which submitters will leave unlabelled.

General requirements:

• All issues must describe a single, actionable topic.
• Complex issues should be split into simpler, possibly related, issues.
• enhancement issues:
  • Must describe the use-case, benefits and tradeoffs.
  • Should include sample code demonstrating the enhancement in action.
  • Should take the Checklist for Python library APIs into consideration.
• bug issues must:
  • Be explicitly reported against either the latest PyPI released version or the current GitHub master branch.
  • Describe the steps to reproduce the bug, ideally with a minimal code sample.
  • Describe the expected and actual results.
  • Include a reference to where the documentation is inconsistent with the actual results.
• maintenance issues:
  • Must describe the purpose, benefits and trade-offs.

Warning

Open development issues not meeting these requirements will be either discarded and closed, or worked on, at the maintainer’s discretion.

Pull Requests

Pull Requests are tracked here and:

• Must reference an existing, open issue, and preferably only one.
• May totally or partially contribute to closing the referenced open issue.
• Will not be merged if any of the GitHub checks fails.
• Will not necessarily be merged if all of the GitHub checks pass.
• Must be assigned to the same milestone as the referenced open issue.
• May be labelled.

Release Procedure

Confirm that the NEXT milestone contains:

• No open issues.
• One or more closed issues, each associated with one or more merged Pull Requests.

Once confirmed, rename the NEXT milestone to YY.MINOR.MICRO and create a new issue in it, labelled release and named “Release”. Then:

• Update __version__ in src/wires/__init__.py to YY.MINOR.MICRO.

• Confirm that the documentation builds successfully, making adjustments if needed.

• Update the Change Log:

  • Run towncrier --draft and confirm the output.
  • If needed, add missing .deprecate, .enhancement, .bug or .other news-fragment files under docs/newsfragments.
  • Once the draft output looks correct, run towncrier.

• Commit the version, documentation and changelog changes, tagging it YY.MINOR.MICRO.

• Create Pull Request against the “Release” issue.

• Once all the GitHub checks pass, merge the Pull Request.

• Update the local repository with the GitHub merged changes.

• Release in PyPI:

  • Install release dependencies:

    $ pip install -e .[release]
    

  • Build the release artifacts:

    $ rm -r build/ dist/
    $ python setup.py sdist bdist_wheel
    

  • Upload to test PyPI:

    $ twine upload -r test dist/wires-*
    

  • Test the installation into a freshly created virtual environment:

    $ pip install -i https://test.pypi.org/pypi wires
    

  • If ok, upload to PyPI:

    $ twine upload -r pypi dist/wires-*
    

  • Confirm the installation into a freshly created virtual environment:

    $ pip install wires
    

  • Lastly, cleanup again:

    $ rm -r build/ dist/
    

• Confirm the versioned documentation is available at Read the Docs.

• Close the YY.MINOR.MICRO milestone.

• Lastly, create a new NEXT milestone.