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 sandra.smit@wur.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.

Writing in Markdown

Most of the writing that you'll do will be in Markdown. You can think of Markdown as a few little symbols around your text that will allow GitLab to render the text with a little bit of formatting. For example, you could write words as bold (**bold**), or in italics (_italics_), or as a link ([link](https://youtu.be/dQw4w9WgXcQ)) to another webpage.

Also when writing in Markdown, please start each new sentence on a new line. Having each sentence on a new line will make no difference to how the text is displayed, there will still be paragraphs, but it makes the diffs produced during the merge request review easier to read!

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 master				#Get the pantools content.
git push --set-upstream origin master	#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 "[WIP]" at the start of the merge request title, which stands for "Work in Progress". When you are happy with it and are happy for it to be merged into the main repository, change the "[WIP]" in the title of the merge request to "[Ready for review]".

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 build, and run PanTools.

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.

• Astrid van der Brandt
• Dirk-Jan van Workum
• Eef Jonkheer
• Matthijs Moed
• Sandra Smit
• Siavash Sheikhizadeh
• Thijs van Lankveld

---

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