[plum] Contribution Standards, Guidance and Workflow¶
This page describes the coding, testing, and documentation standards as well as the workflow that must be followed to contribute to this project.
Within the standards, sentences with the word “SHALL” are required. Those without “SHALL” are strongly suggested and should be followed unless there is a very good reason to deviate.
These standards apply both to restructured text pages and docstrings.
- Use active voice.
- Reference pages.
- An entry SHALL be included for every public API.
- An example code block should demonstrate a single concept. Instead of covering multiple topics in a single example code block, break it up into multiple example code blocks (it’s OK if examples build on one another, especially not repeating imports within a section).
- Documentation SHALL build successfully using Sphinx (per configuration within the CI/CD pipeline jobs)
pep8 should be followed.
All code in src folder shall pass mypy.
Code SHALL pass PyLint (per configuration within CI/CD pipeline jobs).
- PyLint configuration limits are at reasonable limits. For cases where an exception is warranted, use PyLint suppression markup (preferably with a comment explaining why it’s warranted).
Code SHALL pass PyTest regression tests (per configuration within CI/CD pipeline jobs).
- All tests SHALL pass.
Regression tests SHALL provide 100% code coverage (CI/CD pipelines verify this). Code branches deemed covered by inspection and not worth having regression tests for SHALL be marked with
# pragma: no cover.
A single test case should focus on testing one thing (e.g. exercising one variation of one argument in a call).
A group of related test cases should be organized within a test case class (e.g. exercising all the variations of one argument in a call).
A test file should focus on testing one program construct (e.g. a class, a complex function, or a module with very simple constructs).
Restrict contribution to a single feature or anomaly fix.
Get setup with a GitLab account: https://gitlab.com
Get setup with Git.
Clone the plum repository from GitLab: https://gitlab.com/dangass/plum
Create branch off of the “master” branch.
Read and sign the
contribution_waiver.txtat the root of the repository.
Update documentation in
Add entry to
docs/release_notes.rstdescribing the change.
- Keep user perspective in mind.
- Do NOT summarize code differences or implementation details.
- If contributing an anomaly fix, describe previous behaviors and under what conditions it occurred (e.g. what type of exception happened? what specific sequence of events led to it?). Then describe how it behaves now (skip this if no value added).
- List names and short descriptions of new API’s (use bullets if multiple).
If changing API, update reference and tutorial pages.
Update regression tests.
- If contributing an anomaly fix, add a regression test that exposes the anomaly and tests for the correct behavior.
- If contributing a feature, add regression tests that thoroughly exercises the new functionality.
Implement the anomaly fix or new feature.
Locally run CI/CD pipeline activities (inspect CI/CD configuration to discover tox commands to use).
- Use PyLint to check your code.
- Run the regression tests.
- Build the documentation.
Push branch to project GitLab server.
Inspect associated GitLab pipeline and ensure it passed (all green).
Create merge request.
Create/check out branch.
Edit setup.py and increment the revision number.
Add entry to
Commit and push branch to the central repository.
Ensure CI/CD pipeline passes
Get command prompt with current working directory at root of plum repository
$ python -m pip install wheel twine
Change directories into the top directory of the repository:
$ cd plum
Remove old builds:
$ rm dist/*
Build the plum-py package:
$ python setup.py bdist_wheel sdist --formats=gztar
Upload to PyPi
$ python -m twine upload dist/*
Alternatively, do both build and upload at same time:
$ python setup.py bdist_wheel upload
Tag commit in GitLab with the version number.