Skip to content

Latest commit

 

History

History
52 lines (34 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

52 lines (34 loc) · 4.15 KB
Raw

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Contributions to this project are released to the public under the project's open source license.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Developing a fix/feature

Annotated Logger uses ruff, pytest, pyright and mutmut for testing and linting. It uses hatch as a project manager to build and install dependencies. When developing locally it's suggested that you ensure that your editor supports ruff and pyright for inline linting. The pytest test suite is very quick and should be run frequently. (mutmut)[https://github.com/boxed/mutmut] is a mutation testing tool and is fairly slow as it runs the other three tools hundreds of times after making minor tweaks to the code. It will typically be run only once development is complete to ensure everything is fully tested.

script/mutmut_runner is what mutmut uses to see if the mutation fails, however, it's also quite useful on it's own as it runs ruff, pytest and pyright exiting as soon as anything fails, so it makes a good sanity check.

In addition to the tests and linting above all PRs will compare the version number in __init__.py with the version in main to ensure that new PRs results in new versions.

Submitting a pull request

  1. Fork and clone the repository
  2. Configure and install the dependencies: script/bootstrap
  3. Make sure the tests pass on your machine: hatch run dev:test
  4. Make sure linting passes: hatch run dev:lint and hatch run dev:typing
  5. Create a new branch: git checkout -b my-branch-name
  6. Make your change, add tests, and make sure the tests still pass
  7. Push to your fork and submit a pull request
  8. Pat yourself on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Follow the style guide.
  • Write tests.
  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
  • Write a good commit message.

Release a Version

Releasing a version is as simple as creating and pushing a tag. A few rules are enforced for tags, the tag must be signed, they cannot be updated or deleted and Coverage, pyright and ruff must be passing (Coverage ensures the pytest matrix also passed).

Simply run git tag --sign v0.0.0 (inserting the correct version). Then, git push origin v0.0.0. CI will build, publish to Pypi and then create a GitHub Release with the artifacts.

Technically, the tag name does not matter, it's not used for the version published, that pulls from __init__.py. But, it is how anyone will be able to browse the code at a particular version, so it should be set correctly.

All commits pushed to the repo will also be built and pushed to testpypi. This CI job will fail if the version already exists there. During development set a version in the pattern of 0.0.0.dev0 and increment dev0 for every new release you'd like to test externally. Then, you can install the package from testpypi. Once the release is finalized, remove the dev from the version and ensure the version is updated following semver by bumping the major, minor or patch version as appropriate.

Resources