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__
insrc/wires/__init__.py
toYY.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 underdocs/newsfragments
. - Once the draft output looks correct, run
towncrier
.
- Run
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.