Welcome to the Drawdown Solutions repository! We're excited that you're here and want to help with solutions to climate change.
These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an issue!
Before you start you'll need to set up a free GitHub account and sign in. Here are some instructions. If you are not familiar with version control systems such as git, introductions and tutorials may be found on ReproducibleImaging.org.
Already know what you're looking for in this guide? Jump to the following sections:
The current list of issue labels are here and include:
-
These issues point to problems in the project.If you find new a bug, please provide as much information as possible to recreate the error.
If you experience the same bug as one already listed in an open issue, please add any additional information that you have as a comment.
-
These issues contain a task that any developer can help with, without having to come up to speed on the rest of the system.
We appreciate all contributions to Drawdown Solutions, but those most easily accepted will follow a workflow similar to the following:
-
Comment on an existing issue or open a new issue referencing your addition.
This allows other members of the development team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.
This blog is a nice explanation of why putting this work in up front is so useful to everyone involved.
Discussing the change first is especially important for substantive changes to be made in the model directory. The Drawdown methodology has been published and undergone substantial peer review. Changes to the model have to be vetted, and ensure that they fit within the reviewed methodology.
-
Fork the Drawdown Solutions repository to your profile.
This is now your own unique copy of the codebase. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code.
Make sure to keep your fork up to date with the original repository. One way to do this is to configure a new remote named "upstream" and to sync your fork with the upstream repository.
-
Make the changes you've discussed.
When you are working on your changes, test frequently to ensure you are not breaking the existing code. The project uses pytest, and "make test" will invoke pytest with appropriate options. There is a YouTube video describing the different levels of testing.
It's a good practice to create a new branch of the repository for a new set of changes.
-
Submit a pull request.
A new pull request for your changes should be created from your fork of the repository.
Pull requests should be submitted early and often (please don't mix too many unrelated changes within one PR)! If your pull request is not yet ready to be merged, please also include the [WIP] prefix (you can remove it once your PR is ready to be merged). This tells the development team that your pull request is a "work-in-progress", and that you plan to continue working on it.
Review and discussion on new code can begin well before the work is complete, and the more discussion the better. The development team may prefer a different path than you've outlined, so it's better to discuss it and get approval at the early stage of your work.
Once your PR is ready a member of the development team will review your changes to confirm that they can be merged into the main codebase.
New code should be tested. Test coverage is a key deliverable of this project, we want the codebase to be amenable to extensions by the annual cohort of researchers and good coverage is essential to that.
Bug fixes must include an example that exposes the issue. New features should have tests that exercise its functionality. There is a YouTube video describing the layers of testing. If you're not sure what this means for your code, please ask in your pull request.
Please review the individual README based on which project you are contributing
- Web Application README
- Service Application README
We welcome and recognize all contributions from documentation to testing to code development.
You can see a list of current contributors in our zenodo file, which we use to generate author lists as described in this blog post. If you are new to the project, don't forget to add your name and affiliation there!
You're awesome. 👋😃
— Based on contributing guidelines from the Nipype project, which was itself based on contributing guidelines from the STEMMRoleModels project.