CONTRIBUTING.md

Contributing to PanTools

Get in touch

There are many ways to get in touch with the PanTools team!

• GitLab issues and 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! (See our Where to start: issues section below.)
• Contact the Project Lead of the PanTools project - Sandra Smit - by email at pantools@bioinformatics.nl.

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

In order to contribute via GitLab, you'll need to set up an account and sign in. Remember that you can ask us any questions you need to along the way.

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

We appreciate all contributions to PanTools. THANK YOU for helping us build this useful resource.

All project management, conversations and questions related to the PanTools project happens here in the PanTools repository.

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 PanTools 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 PanTools repository website. You can request a guest role by getting in touch.

Alternatively, you can send an email to create a new issue. The title of the email will be used as the issue title and the email body will be put in the issue description. Note that we are in the process of setting up this email functionality; when this is done, we will update the email link here.

2. Fork the PanTools repository

This is now your own unique copy of PanTools. 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 main repository, otherwise, you can end up with lots of dreaded merge conflicts.

The repository website only provides functionality for forking inside the same server (git.wur.nl). You can fork the PanTools project onto another GitLab server. Forking onto a GitHub server is currently not possible, but this is being worked on. First create a blank repository on GitLab, let's assume it's called https://gitlab.com/johndoe/my-pantools. Use the following commands in a directory where you wish to fork PanTools.

mkdir my-pantools
cd my-pantools
git init
git remote add origin https://gitlab.com/johndoe/my-pantools
git remote add upstream https://git.wur.nl/bioinformatics/pantools
#There are now two remotes: origin (your remote fork) and upstream (the pantools repository).

git pull upstream develop				#Get the pantools content.
git push --set-upstream origin develop	#Push this content to the origin (fork).

3. Make the changes you've discussed

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. This blog explains how to write a good Git commit message and why it matters. It is also perfectly fine to have a lot of commits - including ones that break code. A good rule of thumb is to push up to GitLab when you do have passing tests then the continuous integration (CI) has a good chance of passing everything.

If you feel tempted to "branch out" then please make a new branch and a new issue to go with it. This blog details the different Git branching models.

Please do not re-write history! That is, please do not use the rebase command to edit previous commit messages, combine multiple commits into one, or delete or revert commits that are no longer necessary.

Are you new to Git and GitLab or just want a detailed guide on getting started with version control? Check out the Version Control chapter in The Turing Way Book!

4. Submit a merge request

We encourage you to open a merge request as early in your contributing process as possible. This allows everyone to see what is currently being worked on. It also provides you, the contributor, feedback in real-time from both the community and the continuous integration as you make commits (which will help prevent stuff from breaking).

When you are ready to submit a merge request, please describe in the merge request body:

• The problem you're trying to fix in the merge request, reference any related issue and use fixes/close to automatically close them, if pertinent.
• A list of changes proposed in the merge request.
• What the reviewer should concentrate their feedback on.

By providing as much detail as possible, you will make it really easy for someone to review your contribution!

If you have opened the merge request early and know that its contents are not ready for review or to be merged, add "Draft: " at the start of the merge request title. When you are happy with it and are happy for it to be merged into the main repository, remove the "Draft: " in the title of the merge request.

Please make sure to select the correct target branch for your merge request. For most cases, this will be the develop branch. Also see the section about Git organization for more information on the branching model used in PanTools.

A member of the PanTools team will then review your changes to confirm that they can be merged into the main repository. A review will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitLab notifications and be prepared to join in that conversation.

You can update your fork of the PanTools repository and the merge request will automatically update with those changes. You don't need to submit a new merge request when you make a change in response to a review.

You can also submit merge requests to other contributors' branches! Do you see an open merge request that you find interesting and want to contribute to? Simply make your edits on their files and open a merge request to their branch!

GitLab has a nice introduction to the merge request workflow, but please get in touch if you have any questions.

Local development

You can build and run PanTools locally. Please refer to the manual for instructions on how to setup, build, and run PanTools. This is a short-list of important parts of our setup:

• We use pre-commit to run checks before committing.
• We use IntelliJ IDEA as our IDE.
• We use Maven as our build tool.
• We use log4j2 for logging.
• We use ReadTheDocs for our documentation.
• We use Snakemake for our end-to-end tests in the CI/CD pipeline.

Git organization

The PanTools project uses the following branching model:

%%{init: { 'gitGraph': {'mainBranchName': "pantools_v4", 'showCommitLabel': false }} }%%
gitGraph:
  options
    {
      "node-revert-next-line": false,
      "node-revert-commit": false
    }
  end
  commit
  branch develop order: 2
  commit
  checkout develop
  branch add_small_feature1 order: 3
  commit
  commit
  commit
  checkout develop
  branch add_big_feature order: 4
  commit
  commit
  checkout develop
  merge add_small_feature1
  checkout develop
  branch add_small_feature2 order: 3
  commit
  commit
  checkout develop
  merge add_small_feature2
  checkout add_big_feature
  commit
  commit
  merge develop
  commit
  checkout develop
  branch release_v4.3.1 order: 1
  commit
  checkout pantools_v4
  merge release_v4.3.1 tag: "v4.3.1"
  commit
  checkout develop
  merge release_v4.3.1
  merge add_big_feature
  commit

• pantools_v4 is the main branch of the PanTools project. This branch should always be stable and contain the latest release of PanTools.
• develop is the branch where all new features are developed. This branch should always be stable and contain the latest development version of PanTools.
• release_v4.3.1 is a release branch. When a new release is ready, a release branch is created from develop. In this release branch, only updates necessary for the release are made (e.g. version number updates, critical minor bugs, etc.). The release branch is merged into pantools_v4 and tagged with the release version. The release branch is also merged back into develop to make sure that the release is also part of the development version.
• Feature branches are created from develop and merged back into develop when the feature is ready. Make sure to keep your feature branches up-to-date with develop by regularly merging develop into your feature branch.

Recognizing Contributions

We welcome and recognise all kinds of contributions, from fixing small errors, to developing documentation, maintaining the project infrastructure, writing code or reviewing existing resources.

Current Contributors

The PanTools team wants to graciously thank the following people for their contributions to the PanTools project.

• Sandra Smit
• Dick de Ridder
• Siavash Sheikhizadeh
• Eef Jonkheer
• Dirk-Jan van Workum
• Robin van Esch
• Matthijs Moed
• Nauman Ahmed
• Thijs van Lankveld
• Astrid van den Brandt
• Meixin Yang
• Lakhansing Pardeshi

---

These Contributing Guidelines have been adapted from the Contributing Guidelines of the BIDS Starter Kit! (License: CC-BY)