CONTRIBUTING.md

Guidelines for contributing

Table of Contents

• Guidelines for contributing
  • Summary
  • Git
  • Python
    • Pdm
      • Highlights
      • Key commands
    • Testing with pytest
  • GitHub Actions workflows
  • Maintainers

Summary

PRs welcome!

• Consider starting a discussion to see if there's interest in what you want to do.
• Submit PRs from feature branches on forks to the develop branch.
• Ensure PRs pass all CI checks.
• Maintain test coverage at 100%.

Git

• Why use Git? Git enables creation of multiple versions of a code repository called branches, with the ability to track and undo changes in detail.
• Install Git by downloading from the website, or with a package manager like Homebrew.
• Configure Git to connect to GitHub with SSH.
• Fork this repo.
• Create a branch in your fork.
• Commit your changes with a properly-formatted Git commit message.
• Create a pull request (PR) to incorporate your changes into the upstream project you forked.

Python

Pdm

This project uses PDM for dependency management and packaging.

Highlights

• Automatic virtual environment management: Automatically manages the application environment.
• Dependency resolution: Automatically resolve any dependency version conflicts using the pip dependency resolver.
• Dependency separation: Supports separate lists of optional dependencies in the pyproject.toml. Production installs can skip optional dependencies for speed.
• Builds: Features for easily building the project into a Python package and publishing the package to PyPI.

Key commands

pdm init  # Initialize a new project
pdm add PACKAGE_NAME  # Add a package to the project dependencies
pdm install  # Install dependencies from pyproject.toml
pdm list  # Show a list of installed packages
pdm run COMMAND  # Run a command within the PDM environment
pdm shell  # Activate the PDM environment, similar to activating a virtualenv
pdm sync  # Synchronize the project's dependencies

Testing with pytest

• Tests are in the tests/ directory.
• pytest features used include:
  • capturing stdout with capfd
  • fixtures
  • monkeypatch
  • parametrize
  • temporary directories and files (tmp_path and tmp_dir)
• pytest plugins include:
  • pytest-mock
• pytest configuration is in pyproject.toml.
• Run tests with pytest
• Test coverage reports are generated by pytest-cov

GitHub Actions workflows

GitHub Actions is a continuous integration/continuous deployment (CI/CD) service that runs on GitHub repos. It replaces other services like Travis CI. Actions are grouped into workflows and stored in .github/workflows.

Maintainers

• The default branch is main.

• PRs from feature branches should be merged into develop.

• The only merges to main should be PRs from develop.

• Branch protection is enabled on develop and main.

  • develop:
    • Require signed commits
    • Include administrators
    • Allow force pushes
  • main:
    • Require signed commits
    • Include administrators
    • Do not allow force pushes
    • Require status checks to pass before merging (commits must have previously been pushed to develop and passed all checks)

• To commit:

  • Follow the Conventional Commits specification for commit messages. This standardizes the commit history and facilitates automatic generation of the changelog.

  • Type must be one of the following:

    • feat: A new feature
    • fix: A bug fix
    • perf: A code change that improves performance
    • deps: Dependency updates
    • revert: Reverts a previous commit
    • docs: Documentation only changes
    • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc), hidden
    • chore: Miscellaneous chores, hidden
    • refactor: A code change that neither fixes a bug nor adds a feature, hidden
    • test: Adding missing tests or correcting existing tests, hidden
    • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm), hidden
    • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs), hidden

  • Ensure your commit messages clearly describe the changes made and follow the format type(scope?): subject, where scope is optional.

• To create a release:

  • Follow SemVer guidelines when choosing a version number. Note that PEP 440 Python version specifiers and SemVer version specifiers differ, particularly with regard to specifying prereleases. Use syntax compatible with both.
  • The PEP 440 default (like 1.0.0a0) is different from SemVer.
  • An alternative form of the Python prerelease syntax permitted in PEP 440 (like 1.0.0-alpha.0) is compatible with SemVer, and this form should be used when tagging releases.
  • Examples of acceptable tag names: 1.0.0, 1.0.0-alpha.0, 1.0.0-beta.1
  • Push to develop and verify all CI checks pass.
  • Fast-forward merge to main, push, and verify all CI checks pass.