Skip to content
Snippets Groups Projects
Commit 16b05fca authored by Vellekoop, Sam's avatar Vellekoop, Sam
Browse files

docs: add CONTRIBUTING.md

Add Contributing guidelines in order to streamline development.
parent be04113f
Branches
No related tags found
No related merge requests found
# Contributing to MNP
First off, thanks for taking the time to contribute! ❤️
All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways
to help and details about how this project handles them. Please make sure to read the relevant section before making
your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. We
look forward to your contributions. 🎉
## Table of contents
- [Get in touch](#get-in-touch)
- [Contributing through GitLab](#contributing-through-gitlab)
- [Where to start: issues](#where-to-start-issues)
- [Making a change with a merge request (developer, maintainer or owner)](
#making-a-change-with-a-merge-request-developer-maintainer-or-owner)
- [Commit message guidelines](#commit-message-guidelines)
## Get in touch
There are many ways to get in touch with the *MNP* team:
- GitLab [issues][mnp-issues] and [merge requests][mnp-merge-requests]
- Join a discussion, collaborate on an ongoing task and exchange your thoughts with others. You will have to request a
guest role to start contributing.
- Can't find your idea being discussed anywhere? [Open a new issue][new-issue]! (See our
[Where to start: issues](#where-to-start-issues) section below.)
- Contact the maintainers of the *MNP* project by email at [sam.vellekoop@wur.nl](mailto:sam.vellekoop@wur.nl) or
[hans.roelofsen@wur.nl](mailto:hans.roelofsen@wur.nl).
## Contributing through GitLab
[Git][git] is a really useful tool for version control.
[GitLab][gitlab] sits on top of Git and supports collaborative and distributed working.
We know that it can be daunting to start using Git and GitLab if you haven't worked with them in the past, but the *MNP*
maintainers are here to help you figure out any of the jargon or confusing instructions you encounter.
GitLab has a helpful page on [getting started with GitLab][gitlab-getting-started]. Other useful info on Git and version
control can be found here:
- [Version control with git](
https://alan-turing-institute.github.io/rse-course/html/module04_version_control_with_git/index.html)
- [The Turing Way - VCS](https://book.the-turing-way.org/reproducible-research/vcs)
## Where to start: issues
Before you open a new issue, please check if any of our [open issues][open-issues] cover your idea already.
## Making a change with a merge request (developer, maintainer or owner)
The following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with
ease.
### 1. Comment on an [existing issue][mnp-issues] or open a new issue referencing your addition
This allows other members of the *MNP* 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](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) is a nice explanation of why putting this
work in upfront is so useful to everyone involved.
You will need a guest role to create new issues using the *MNP* repository website. You can request a guest role
by [getting in touch](#get-in-touch).
### 2. Create new merge request
When you've been assigned an open [issue][open-issues] or assigned yourself to one, you can create a new merge request
for that issue.
### 3. Clone the [*MNP* repository][mnp-repo]
This is now your local copy of *MNP*.
Changes here won't affect anyone else's work (*yet*), so it's a safe space to explore edits to the code!
Make sure to keep your local repository up to date with the upstream repository, otherwise, you can end up with lots
of dreaded [merge conflicts][gitlab-merge-conflicts].
### 4. Install the *MNP* package and requirements
In your local environment ([venv](https://docs.python.org/3/library/venv.html) or
[conda](https://github.com/conda-forge/miniforge)), install the mnp package. Since you will be developing, make sure to
install the development requirements as well:
~~~
# make sure you are in the same directory as the pyproject.toml and have your virtual environmnent activated
pip install -e .[dev] # install mnp in editable mode and install the development requirements as well
pre-commit install # install git hooks
pre-commit # run pre-commit to see if the git hooks run and all tests pass (they should)
~~~
### 5. Make the changes you've discussed
Checkout the branch for the merge request and make sure it's up to date. Now you can start making changes.
Try to keep the changes focused. If you submit a large amount of work all in one go it will be much more work for
whoever is reviewing your merge request.
While making your changes, commit often and write good, detailed commit messages. For this project we use the
[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. See the
[commit message guidelines](#commit-message-guidelines) for more information.
It is perfectly fine to have a lot of commits. When fixing a bug or adding a new feature, make sure to add unittests
showing that your solution is working.
A good rule of thumb is to push up to GitLab when you *do* have passing tests.
When you feel like your work for the issue is done, or if you are stuck, you can assign a reviewer for the merge
request. The reviewer can then approve the changes or give feedback.
### 6. The branch is merged into master
Maintainers or owners of the *MNP* project will merge the changes into the master branch.
## Commit message guidelines
Based on the
[Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)
We make use of the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This leads to
more readable messages that are easy to follow when looking through the project history. But also, we use the git commit
messages to bump the *MNP* version.
### Commit Message Format
Each commit message consists of a **header** and optionally a **body** and a **footer**. The header has a special
format that includes a **type**, a **scope** and a **subject**:
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
The **header** is mandatory and the **scope** of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitLab as well as in various git tools.
The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.
Samples:
```
docs(species_models): add docstrings to HSI class
```
```
fix(aggregate_land_types): fix bug where last row of land types is not aggregated
```
### Revert
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
### Type
Must be one of the following:
* **build**: Changes that affect the build system or external dependencies (example scopes: pyproject.toml)
* **ci**: Changes to our CI configuration files and scripts (example scopes: GitLab)
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests
### Scope
Scope should be the name of the module affected by the changes.
### Subject
The subject contains a succinct description of the change:
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end
### Body
The body should include the motivation for the change and contrast this with previous behavior.
### Footer
The footer should contain any information about **Breaking Changes** and is also the place to
reference GitLab issues that this commit closes.
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit
message is then used for this.
---
*These Contributing guidelines have been adapted from the
[Contributing guidelines](https://git.wur.nl/bioinformatics/pantools/-/blob/pantools_v4/CONTRIBUTING.md) of PanTools*
[mnp-repo]: https://git.wur.nl/MNP/mnp/
[mnp-issues]: https://git.wur.nl/MNP/mnp/issues
[new-issue]: https://git.wur.nl/MNP/mnp/issues/new
[open-issues]: https://git.wur.nl/MNP/mnp/issues?scope=all&state=opened
[mnp-merge-requests]: https://git.wur.nl/MNP/mnp/merge_requests
[git]: https://git-scm.com
[gitlab]: https://gitlab.com
[gitlab-getting-started]: https://about.gitlab.com/get-started/
[gitlab-merge-conflicts]: https://docs.gitlab.com/ee/topics/git/merge_conflicts.html
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment