Skip to content

Latest commit

 

History

History
92 lines (62 loc) · 5.45 KB

CONTRIBUTING.md

File metadata and controls

92 lines (62 loc) · 5.45 KB

Contributing to EP-BOLFI

If you'd like to contribute to EP-BOLFI, thank you very much and please have a look at the guidelines below.

Workflow

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

Before you begin

  1. Create an issue where new proposals can be discussed before any coding is done.
  2. Download the source code onto your local system, by cloning the repository:
git clone https://github.com/YannickNoelStephanKuhn/EP-BOLFI
  1. Install the library in editable mode:
pip install -e ep-bolfi
  1. Create a branch of this repo, where all changes will be made, and "checkout" that branch so that your changes live in that branch:
git branch <branch_name>
git checkout <branch_name>

Or as a short-hand:

git checkout -b <branch_name>

Writing your code

  1. EP-BOLFI is written in Python, and makes heavy use of ELFI as well as PyBaMM.
  2. Make sure to follow our coding style guidelines.
  3. Commit your changes to your branch with useful, descriptive commit messages: Remember these are visible to all and should still make sense a few months ahead in time. While developing, you can keep using the GitLab issue you're working on as a place for discussion. Refer to your commits when discussing specific lines of code.
  4. If you want to add a dependency on another library, or re-use code you found somewhere else, have a look at these guidelines.

Merging your changes with EP-BOLFI

  1. Make sure that your code runs successfully. Ideally, implement tests.
  2. Run flake8 on your code to fix formatting issues ahead of time.
  3. When you feel your code is finished, or at least warrants serious discussion, create a merge request (MR) on the GitHub page of EP-BOLFI.
  4. Once a MR has been created, it will be reviewed by any member of the group. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitLab permissions will merge your changes into the EP-BOLFI main repository.

Coding style guidelines

EP-BOLFI 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.

Flake8

We use flake8 to check our PEP8 adherence. To try this on your system, navigate to the ep_bolfi directory in a terminal and type:

flake8

Documentation

The documentation is generated with Sphinx from the source code.

Hence, please write the in-code documentation for your own comments as reStructuredText.

Dependencies and reusing code

While it's a bad idea for developers to "reinvent the wheel", it's important for users to get a reasonably sized download and an easy install. In addition, external libraries can sometimes cease to be supported, and when they contain bugs it might take a while before fixes become available as automatic downloads to EP-BOLFI users. For these reasons, all dependencies in EP-BOLFI should be thought about carefully, and discussed on GitHub.

Direct inclusion of code from other packages is possible, as long as their license permits it and is compatible with ours, but again should be considered carefully and discussed in the group. Snippets from blogs and stackoverflow are often incompatible with other licences than CC BY-SA and hence should be avoided. You should attribute (and document) any included code from other packages, by making a comment with a link in the source code.

Building from source

Build and install wheel from source (pip)

Install the build command and execute it:

pip install build
python3 -m build

The wheel file should be at dist/ep_bolfi-3.0-py3-none-any.whl. Please do not commit these.

Infrastructure

GitLab

GitLab 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.
  • This file, CONTRIBUTING.md is recognised as the contribution guidelines and a link is automatically displayed when new issues or pull requests are created.

Acknowledgements

This CONTRIBUTING.md file was adapted from the excellent Pints GitHub repo.