3. Contribution Guide

We are thrilled that you have decided to join the Breakthrough Energy Sciences (BES) community and help develop and improve this software! We wrote the following guidelines to ensure that your contribution is consistent with our coding standards and hence facilitate its merging into the code base.

There are several ways to contribute to this project. You can report bugs, file feature requests, work on existing issues, etc. In order to keep the code base well structured, documented and testable we have written guidelines. When creating a pull request the following items should be addressed. The reviewer will make sure the guidelines are followed.

Thank you for joining the BES community!

3.1. How to Contribute

  1. First things first, go to the Installation Guide to get the software up and running

  2. Get familiar with our Git/GitHub workflow (see our Working with Git/GitHub for more details)

  3. Reporting a bug or have a feature request? (see the Bug Report and Feature Request section)

  4. Does your feature require external data? (see the Data Intake Procedure section)

  5. Develop your feature (go to the Develop your Feature section)

  6. Format your code (as explained in the Format your Code section)

  7. Document your code (see the Document your Code section)

  8. Make a pull request (see our Working with Git/GitHub page)

3.1.1. Bug Report and Feature Request

Thank you for reporting your bug or requesting a feature. Navigate to the repository you have identified as the most likely source of your bug or where you think your feature may belong to.

If you are not sure if your bug is really a bug, but rather stems from you individual setup or installation, then use the #questions slack channel to discuss your issue. If you want to discuss your feature request first with the team, feel free to connect with us via the #request_software slack channel.

If you are clear about your bug or feature request, choose the Issues tab on the repository and create a New Issue. If available, choose the Bug report or Feature request template and select Get started. Please fill out the template and provide as much information regarding your bug or feature request. Click on Submit new issue and the team will get back to you regarding your issue.

3.1.2. Data Intake Procedure

Before using any external dataset in your project, we must be absolutely certain that it can be redistributed. This applies to both data obtained via an API and data files that are first downloaded and then uploaded to one of our repository on GitHub or any public storage.

A feature relying on external data will not be merged to the code base unless those can be redistributed; therefore it would be a waste of time to write code centered around an external dataset before knowing if it can be used. For this reason, we ask you to follow the below procedure if you should need external data to develop your feature:

  1. Create an issue on GitHub using the data intake template, available in PreREISE, PowerSimData and PostREISE repositories. Fill out all the fields. Make sure the issue has data intake as label and that Daniel Olsen and Benjamin Rouillé d’Orfeuil are assigned to the issue.

  2. The BES team makes sure the data can be used/redistributed.

  3. If the data can be used Daniel and/or Ben communicate the eventual legal note to be added to the ATTRIBUTION file, located in the root directory of the repository, to the collaborator.

  4. Daniel and Ben will review the ATTRIBUTION file and hence should be added as reviewers of your Pull Request.

3.1.3. Develop your Feature

First, we recommend reading the Coding Standards to ensure your code is well designed.

Second, test your feature. The unit tests for our code are grouped locally in a tests folder located at the same level as the module being tested. All the tests of a package can be run using:

pytest -m "not integration"

at the base directory of the repository. The marker in the above command line is used to deselect tests that rely on internal infrastructure.

Best practices for writing tests with pytest and a presentation of the mock objects can be found in our Testing Guide.

3.1.4. Format your Code

Below are the rules:

  • Do not use wildcard imports

  • Do use absolute imports

  • Code is formatted according to the black code style and imports are arranged using isort. This is automatically done running:

    tox -e format

More context and examples about imports can be found in the Import Statement Guide.

3.1.5. Document your Code

All functions and methods of classes must be documented following PEP 257.

There are multiple docstring formats. For this project, we adopted the Sphinx docstring format which allows us to generate documentation for the code together with this website.

You can learn about our docstring convention in the Docstring Guide.

3.2. Communication

Use GitHub to report bugs and propose features. Also, do not hesitate to subscribe to our email list and join our Slack workspace in order to stay updated and reach us if you should have any questions.

We have a Code of Conduct that we ask you to review before communicating on these channels.