diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..0142a53d0ff84c12da52a91c02b1e88f225fbcaa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,198 @@ +# 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