Skip to content

Latest commit

 

History

History
141 lines (85 loc) · 8.54 KB

CONTRIBUTING.md

File metadata and controls

141 lines (85 loc) · 8.54 KB
Raw

Contributing to pybamm-cookie

If you'd like to contribute to this project, please have a look at the guidelines below.

If you're already familiar with our workflow, maybe have a quick look at the pre-commit checks directly below.

pre-commit checks

Before you commit any code, please perform the following checks:

Installing and using pre-commit

pybamm-cookie uses a set of pre-commit hooks and the pre-commit bot to format and prettify the codebase. The hooks can be installed locally using -

pip install pre-commit
pre-commit install

This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using -

pre-commit run --all-files

If you would like to skip the failing checks and push the code for further discussion, use the --no-verify option with git commit.

Workflow

We use Git and GitHub to coordinate our work. When making any kind of update, we try to follow the procedure below.

A. Before you begin

  1. Create an issue where new proposals can be discussed before any coding is done.
  2. Create a branch of this repo (ideally on your own fork), where all changes will be made.
  3. Download the source code onto your local system, by cloning the repository (or your fork of the repository).
  4. Use nox -s dev or pip install -e .[dev] to install pybamm-cookie in editable/development mode.
  5. Test if your installation worked, using the test script: nox -s test-generation or pytest.

You now have everything you need to start making changes!

B. Writing your code

  1. This project is developed in Python), and uses the copier templating tool. For testing, we use pytest.
  2. Make sure to follow our coding style guidelines.
  3. Commit your changes to your branch with useful, descriptive commit messages: Remember these are publicly visible and should still make sense a few months ahead in time. While developing, you can keep using the GitHub issue you're working on as a place for discussion.

C. Merging your changes with pybamm-cookie

  1. Test your code!
  2. When you feel your code is finished, or at least warrants serious discussion, run the pre-commit checks and then create a pull request (PR) on pybamm-cookie's GitHub page.
  3. Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into pybamm-cookie main repository.

Coding style guidelines

This project follows the PEP8 recommendations for coding style. These are very common guidelines, and community tools have been developed to check how well projects implement them. We recommend using pre-commit hooks to check your code before committing it. See installing and using pre-commit section for more details.

Ruff

We use ruff to check our PEP8 adherence. To try this on your system, navigate to the parent pybamm-cookie directory in a console and type

python -m pip install pre-commit
pre-commit run ruff

Ruff is configured inside the file pre-commit-config.yaml, allowing us to ignore some errors. If you think some rules should be added or removed, please submit an issue.

If you performed the pre-commit install step above, your code changes will be checked against Ruff automatically when you try to commit them (see Pre-commit checks).

Testing

All code requires testing. We use the Pytest package for our tests. (These tests typically just check that the code runs without error, and so, are more debugging than testing in a strict sense. Nevertheless, they are very useful to have!).

If you have nox installed, to run tests for the template, type

nox -s template-tests

else, type

pytest tests/

To test a generated project, meaning a project generated out of pybamm-cookie, you can simply run

nox -s generated-project-tests

Writing tests

Every new feature should have its own test. To create ones, have a look at the test directory and see if there's a test for a similar method. Copy-pasting this is a good way to start.

Next, add some simple (and speedy!) tests of your main features. If these run without exceptions, that's a good start! Next, check the output of your methods using any of these assert methods.

Documentation

First and foremost, every method and every class should have a docstring that describes in plain terms what it does, and what the expected input and output is.

These docstrings can be fairly simple, but can also make use of reStructuredText, a markup language designed specifically for writing technical documentation.

Using Sphinx the documentation in docs can be converted to HTML, PDF, and other formats. In particular, we use it to generate the documentation on http://docs.pybamm.org/

Building the documentation

To test and debug the documentation, it's best to build it locally. To do this, navigate to your pybamm-cookie directory in a console, and then type:

nox -s docs

And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded. In CI, the docs are built and tested using the docs session in the noxfile.py file with warnings turned into errors, to fail the build. The warnings can be removed or ignored by adding the appropriate warning identifier to the suppress_warnings list in docs/conf.py.

Continuous Integration using GitHub Actions

Each change pushed to the pybamm-cookie GitHub repository will trigger the tests to be run, using GitHub Actions.

Tests are run for different operating systems, and for all Python versions officially supported by the pybamm-cookie template. If you open a pull request (PR), feedback is directly available on the corresponding page. If all tests pass, a green tick will be displayed next to the corresponding test run. If one or more test(s) fail, a red cross will be displayed instead.

More details can be obtained by clicking on a specific run.

Configuration files for various GitHub Actions workflows can be found in .github/workflows/.

GitHub

GitHub does some magic with particular filenames. In particular:

  • The first page people see when they go to our GitHub page displays the contents of README.md, which is written in the Markdown format. Some guidelines can be found here.
  • The license for using pybamm-cookie is stored in LICENSE, and automatically linked to by GitHub.
  • This file, CONTRIBUTING.md is recognised as the document that lists the contribution guidelines and a link is automatically displayed when new issues or pull requests are created.