[plum] Tutorial: Contribution Standards, Guidance and Workflows

This tutorial 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.

Documentation Standard and Guidance

These standards apply both to restructured text pages and docstrings.

  • Style
    • Use active voice.
  • Docstrings
    • Sphinx style parameter/return markup SHALL be used.
  • Reference pages.
    • An entry SHALL be included for every public API.
    • Only Sphinx auto-doc features SHALL be utilized (i.e. do not include introductory material, examples, explanations, etc.)
  • Tutorials

    • A tutorial should be provided for every feature.
    • Examples within one RST section should not rely on examples from previous sections (i.e. each section should have the necessary imports listed in the first example).
    • 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 (its OK if examples build on one another, especially not repeating imports within a section).
  • General
    • Documentation SHALL build successfully using Sphix (per configuration within the CI/CD pipeline jobs)

Coding Standard and Guidance

  • pep8 should be followed.

  • 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 its warranted).

Regression Test Standard and Guidance

  • Code SHALL pass PyTest regression tests (per configuration within CI/CD pipeline jobs).

    • All tests SHALL pass with AND without plum-boost acceleration.
  • Regression tests SHALL provide 100% code coverage. (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).

Contributor Workflow

  • 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 latest “beta” branch.

  • Read and sign the contribution_waiver.txt at the root of the repository.

  • Update documentation in docs folder.

    • Add entry to docs/release_notes.rst describing 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.

    • If changing Python code that has a “C” boost equivalent, also implement the feature or fix in the “C” boost extension module.
  • 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.

Maintainer Workflow

Beta Releases

  • Create a new “beta” branch off of master.

  • Edit setup.py and increment the revision number.

  • Add entry to docs/release_notes.rst putting a “TBD” in for the date.

  • Commit and push the new branch to the central repository.

  • Accept merge requests into this branch that conform to the standards and followed the guidance.

  • To publish:

    • Edit docs/release_notes.rst filling in the date where “TBD” was placed.

    • Create merge request from the beta branch to the master branch.

    • Accept and deliver merge request.

    • Pull updated master branch to local system.

    • Get command prompt with current working directory at root of plum repository

    • Install wheel and twine packages:

      $ 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
    • Upload to PyPi

      $ python -m twine upload dist/*.whl
    • Alternatively, do both build and upload at same time:

      $ python setup.py bdist_wheel upload