Contributions to the EMAworkbench are very welcome! In this document you will find some information how to do so, and some information for maintainers such as the release process.
Reporting issues, such as bugs or unclairties in the documentation can be done (as usual) via the Issues section. You can also request new features that you would like to see in the EMAworkbench. Please first search if your bug or request already exists.
In case of a bug, please give us as much useful information possible to work with, including your coding environment, code snippets and if necessary a model. Important are the exact steps to reproduce and what you already found out yourself.
Pull requests are very welcome, both to the code itself and the documentation. If you make a code change, make sure to document it well. This can be done inline, which will be picked up by Readthedocs, and in case of a larger feature, also in a tutorial and/or example.
When still working on something, you can also open a draft pull request. This way we can pitch in early and prevent double work.
All Python code follows Black formatting.
If you have never contributed to a git project or specifically a project hosted on GitHub before, here are a few pointers on how to start.
- From the GitHub quickstart: Contributing to projects (note that you can change your OS and preferred method on the top of the page)
- A very extensive guide: How to Contribute to Open Source
GitHub Desktop also makes managing forks and branches easy by using a visual interface.
For a simple single-file code or docs change, you can also just edit any file in this repository from your webbrowser and it wil fork and branch automatically, after which you can open a PR.
This section is targeted at the maintainers
Pull requests should be merged in a way that only atomic commits make it in the main branch. This keeps the git commit history clean and tidy, and therefore useful. This means every commit only pertains one fix or feature, and can't be breaked into multiple commits without breaking things. It also means no merge commits are allowed. For more about atomic commits, see one and two.
There are two ways to do this:
- For (reducing to) a single commit: Use the Squash and merge button in the GitHub UI. Make sure the commit message and description are properly formatted and contain all the improtant information from the PR when squashing.
- For (keeping) multiple commits: Merge from the command line. First make sure all commits are atomic and contain proper commit messages. Us git amend, reset and rebase if nessesary. Then do a fast-forward merge, using:
In which
git fetch origin git checkout master git merge --ff-only -S origin/BRANCH-TO-MERGE git push originBRANCH-TO-MERGEthe branch is of the PR you want to merge, and-Smakes sure you sign the commits.
The release process has been updated starting at the 2.2.0 release. To create a new release, follow the following steps:
- Make sure all PRs have a clear title and are labeled with at least one label. These will be used when drafting the changelog using the .github/release.yml configuration.
- Go to Releases in the GitHub UI and press the Draft a new release button
- Set the upcoming tag in the Choose a tag and Release title (i.e.
2.3.0) fields - Use the Generate release notes button to auotmatically create release notes. Review them carefully.
- Write a Highlights section with the most important features or changes in this release.
- Copy the release notes and save them with the grey Save draft button.
- Open a new PR in which the version number in ema_workbench/init.py is updated and the copied release notes are added to the CHANGELOG.md.
- Once this PR is merged, go back to the Releases section and Publish the draft release.
- The release.yml CI workflow should now automatically create and upload the package to PyPI. Check if this happened on PyPI.org.
- Finally, open a new PR in which the version number in ema_workbench/init.py is updated towards the next release (i.e.
"2.4.0-dev").