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.