Skip to content

Latest commit

 

History

History
186 lines (116 loc) · 5.5 KB

CONTRIBUTING.md

File metadata and controls

186 lines (116 loc) · 5.5 KB

Contributing

🎉 Thank you for your interest in contributing to this project! 🎉

A couple of quick items:

  1. To avoid duplicate issues and PRs, please search open issue and pull requests before submitting a new one.

  2. The general expectation is to submit a GitHub issue to receive feedback before submitting a pull request (PR) with changes.

    • This will help ensure ideas align with the project scope.

  3. Unit tests should accompany Pull Requests (PRs) whenever possible. 👈

    • This could mean adding additional tests to an existing unit test file or creating a new one.

Ways to Contribute

(in no particular order)

  • Code
  • Documentation
  • Expanding Unit Test coverage (where needed)
  • Helping others (ex: with issue tickets)

Testing Framework

For minimal dependencies, the "batteries included" Python unittest framework is utilized. (Other testing frameworks could be considered should additional testing features be needed.)

Testing can be invoked via make test (more information below)

Development Requirements

  • Python 3
  • GNU Make
  • Docker (Engine)

Important

If your development workstation has a security access control (ex: SELinux) enabled, you will need to put it in a permissive mode for the Docker bind mounts to function.

Development Process

This section consists of suggestions.

It is recommended to verify tests are successful before making any code changes. From there make your changes and run the unit tests to validate there is not code regression.

  1. Create a fork of this project

  2. From the main branch of your fork, create a feature branch

  3. Validate test cases run successfully before any changes are made

  4. Verify linting and formatting checks run successfully before making any changes

  5. Make modifications

  6. Re-test with the existing unit tests against the modified codebase

  7. Add any additional unit tests to improve testing coverage

  8. Re-run the unit tests to confirm they run successfully

  9. Re-run linting and formatting checks

  10. Fix up any linting or formatting errors

  11. When you are satisfied with the changes and it is ready for review, submit a Pull Request (PR)

Using make to streamline linting and testing

This project uses GNU make to simplify the action of interacting with several linters and performing unit testing. Project dependencies and Python virtual environment are managed with uv.

Prequisites

  • Install GNU make for your operating system
  • Install Docker (Engine)

General

Default (all)

  • lint and test
make all

# or simply
make

Clean

  • Removes the Docker images this Makefile utilizes

make clean

Linting

Run all linters in one shot

make lint

Run markdownlint-cli2 for Markdown linting

make mdlint

Run ruff for Python linting

make ruff

Run yamllint for Markdown linting

make yamllint

Testing

Run Python unit tests

make test

But I want to run linting locally

Note

This project uses Docker images to avoid shipping or depending on other projects, package managers, or languages (Node.js, Ruby).

Non-Dockerized local testing is not supported by the repo owner.

There are extra make targets in the Makefile in case you'd prefer local linting and formatting.

make localclean
make localinit
make localmdl
make localruff
make localyaml

Running Unit Tests Manually

Note

This information is somewhat historical since incorporating the Makefile, but could prove useful.

Choose one of the below testing command options that suits your needs.

Important

The commands below are to be run from the top level of the project.

  1. Discover and run unit tests

    • python -m unittest discover

  2. Verbose version of unit test discovery

    • python -m unittest discover -v

  3. Discover unit tests in specific directory (in this case, tests) with verbosity

    • python -m unittest discover -s tests -v

💡 For additional unittest command line options, refer to the official Python unittest documentation.