Skip to content

Latest commit

 

History

History
105 lines (67 loc) · 6.16 KB

CONTRIBUTING.md

File metadata and controls

105 lines (67 loc) · 6.16 KB
Raw

Contributing guidelines

We're really glad you're reading this, because we need volunteer developers to help maintain this project.

Some of the resources to look at if you're interested in contributing:

Licensing

By contributing to osmox, i.e. through opening a pull request, you represent that your contributions are your own original work and that you have the right to license them, and you agree that your contributions are licensed under the MIT license.

Reporting bugs and requesting features

You can open an issue on GitHub to report bugs or request new osmox features. Follow these links to submit your issue:

Submitting changes

Look at the development guide in our documentation for information on how to get set up for development.

To contribute changes:

  1. Fork the project on GitHub.
  2. Create a feature branch to work on in your fork (git checkout -b new-fix-or-feature).
  3. Test your changes using pytest.
  4. Commit your changes to the feature branch (you should have pre-commit installed to ensure your code is correctly formatted when you commit changes).
  5. Push the branch to GitHub (git push origin new-fix-or-feature).
  6. On GitHub, create a new pull request from the feature branch.

Pull requests

Before submitting a pull request, check whether you have:

  • Added your changes to CHANGELOG.md.
  • Added or updated documentation for your changes.
  • Added tests if you implemented new functionality.

When opening a pull request, please provide a clear summary of your changes!

Commit messages

Please try to write clear commit messages. One-line messages are fine for small changes, but bigger changes should look like this:

A brief summary of the commit (max 50 characters)

A paragraph or bullet-point list describing what changed and its impact,
covering as many lines as needed.

Code conventions

Start reading our code and you'll get the hang of it.

We mostly follow the official Style Guide for Python Code (PEP8).

We have chosen to use the uncompromising code formatter black and the linter ruff. When run from the root directory of this repo, pyproject.toml should ensure that formatting and linting fixes are in line with our custom preferences (e.g., 100 character maximum line length). The philosophy behind using black is to have uniform style throughout the project dictated by code. Since black is designed to minimise diffs, and make patches more human readable, this also makes code reviews more efficient. To make this a smooth experience, you should run pre-commit install after setting up your development environment, so that black makes all the necessary fixes to your code each time you commit, and so that ruff will highlight any errors in your code. If you prefer, you can also set up your IDE to run these two tools whenever you save your files, and to have ruff highlight erroneous code directly as you type. Take a look at their documentation for more information on configuring this.

We require all new contributions to have docstrings for all modules, classes and methods. When adding docstrings, we request you use the Google docstring style.

Release checklist

Pre-release

  • Make sure all unit and integration tests pass (This is best done by creating a pre-release pull request).
  • Re-run tutorial Jupyter notebooks (pytest examples/ --overwrite).
  • Make sure documentation builds without errors (mike deploy [version], where [version] is the current minor release of the form X.Y).
  • Make sure the [changelog][changelog] is up-to-date, especially that new features and backward incompatible changes are clearly marked.

Create release

  • Bump the version number in src/osmox/__init__.py
  • Update the [changelog][changelog] with final version number of the form vX.Y.Z, release date, and github compare link (at the bottom of the page).
  • Commit with message Release vX.Y.Z, then add a vX.Y.Z tag.
  • Create a release pull request to verify that the conda package builds successfully.
  • Once the PR is approved and merged, create a release through the GitHub web interface, using the same tag, titling it Release vX.Y.Z and include all the changelog elements that are not flagged as internal.

Post-release

  • Update the changelog, adding a new [Unreleased] heading.
  • Update src/osmox/__init__.py to the next version appended with .dev0, in preparation for the next main commit.

Attribution

The layout and content of this document is partially based on the Calliope project's contribution guidelines.