Skip to content

Latest commit

 

History

History
80 lines (62 loc) · 4.94 KB

CONTRIBUTING.md

File metadata and controls

80 lines (62 loc) · 4.94 KB
Raw

Contribution guide

This applies to all Jolt repositories, unless otherwise noted in a specific repository.

This is a very generalized contribution guide. Information below may not apply to all repositories.

Setting up the environment

  1. Install Python Dungeon Master <https://pdm.fming.dev/latest/>_
  2. Run pdm install -G:all to create a virtual environment <https://docs.python.org/3/tutorial/venv.html>_ and install the dependencies
  3. If you're working on the documentation and need to build it locally, install the extra dependencies with poetry install --with docs
  4. Install pre-commit <https://pre-commit.com/>_
  5. Run pre-commit install to install pre-commit hooks

Code contributions

Workflow

  1. Fork the repository you are wanting to contribute to
  2. Clone your fork locally with git
  3. Set up the environment
  4. Make your changes
  5. (Optional) Run pre-commit run --all-files to run linters and formatters. This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes
  6. Commit your changes to git
  7. Push the changes to your fork
  8. Open a pull request. Give the pull request a descriptive title indicating what it changes. If it has a corresponding open issue, the issue number should be included in the title as well. For example a pull request that fixes issue Bug: Increased stack size making it impossible to find needle #100 could be titled Fix #100 - Make needles easier to find by applying fire to haystack
  9. Add yourself as a contributor to the relevant area using the all-contributors bot

Guidelines for writing code

  • Code should be Pythonic and zen

  • All code should be fully typed . This is enforced via mypy and pyright

    • When requiring complex types, use a type alias.
    • If something cannot be typed correctly due to a limitation of the type checkers, you may use typing.cast to rectify the situation. However, you should only use as a last resort if you've exhausted all other options of type narrowing, such as isinstance() checks and type guards
    • You may use type: ignore if you ensured that a line is correct, but mypy / pyright has issues with it. Don't use blank type: ignore though, and instead supply the specific error code, e.g. type: ignore[attr-defined]

  • If you are adding or modifying existing code, ensure that it's fully tested. 100% test coverage is mandatory, and will be checked on the PR using SonarCloud

  • All functions, methods, classes and attributes should be documented with a docstring. We use the Google docstring style. If you come across a function or method that doesn't conform to this standard, please update it as you go

Writing and running tests

Tests should be contained within the tests directory, and follow the same directory structure as the main package. If you are adding a test case, it should be located within the correct submodule of tests. (e.g., tests for jolt/utils/sync.py should go in tests/utils/test_sync.py.)

If not, you are able to manually run poetry run pytest or pytest tests/

More information on pytest is available here.

Creating a new release

This section applies to repository maintainers only.

  1. Increment the version in pyproject.toml according to the versioning scheme. The version should follow semantic versioning <https://semver.org/>_ and PEP 440 <https://www.python.org/dev/peps/pep-0440/>_.

  2. Draft a new release on GitHub in the repository

    • Use vMAJOR.MINOR.PATCH (e.g. v1.2.3) as both the tag and release title
    • Fill in the release description. You can use the "Generate release notes" function to get a draft for this

  3. Update CHANGELOG.rst by adding a new section, with the version number as a heading. Include the contents of the release notes as they relate to changes in code

  4. Commit your changes and push to main

  5. Publish the release

  6. Check that the "publish" action (Actions tab in the repository) has run successfully