Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • subselection_output_overwriting_keys
  • 36-tag-rasters-in-cover-with-path-of-original-file
  • 35-update-docstrings
  • release-7.4.0
  • refactoring
  • 32-automatisch-versienummer-in-pip-en-python
  • 30-aggregate-land-type-map-only-when-land_type_directory-false
  • MNPHabitattype
  • 7.3.0
  • 7.2.0
  • 7.1.0
  • 7.0.3
13 results
Blame Permalink
After you've reviewed these contribution guidelines, you'll be all set to contribute to this project.
CONTRIBUTING.md 8.81 KiB

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 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

There are many ways to get in touch with the MNP team:

Contributing through GitLab

Git is a really useful tool for version control. 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. Other useful info on Git and version control can be found here:

Where to start: issues

Before you open a new issue, please check if any of our 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 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 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.

2. Create new merge request

When you've been assigned an open issue or assigned yourself to one, you can create a new merge request for that issue.

3. Clone the MNP repository

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.

4. Install the MNP package and requirements

In your local environment (venv or conda), 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 specification. See the 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

We make use of the conventional commits 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 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 of PanTools