🎉🎈🍰 Welcome to The Research Software Reactor repository! 🍰🎈🎉
✨ We're so excited you're here and want to contribute. ✨
The point of this guide is to welcome new users and contributors to this project. We hope that these guidelines are designed to make it as easy as possible to get involved. Don't let trying to be perfect get in the way of being good - we welcome all contributions and would love it if you could follow these guidelines to make sure your contributions can be easily integrated but exciting ideas are more important than perfect pull requests. 💜
If you have any questions that aren't discussed below, please let us know.
- Contributing to The Research Software Reactor
- Contributing through GitHub
- Writing in Markdown
- Where to start: issues
- Making a change with a pull request
- [1. Comment on an existing issue or open a new issue referencing your addition](#1-comment-on-an-existing-issuedevops-issues-or-open-a-new-issue-referencing-your-addition)
- [2. Fork the project's repository to your profile](#2-forkgithub-fork-the-projects-repositorydevops-repo-to-your-profile)
- 3. Make the changes you've discussed
- [4. Submit a pull request](#4-submit-a-pull-requestgithub-pullrequest)
- Recognising Contributions
The research software reactor is a community-oriented and -led project. We therefore require that all contributions adhere to our Code of Conduct.
This project aims to be inclusive to people from all walks of life. This should be taken into account in contributions.
The following are examples of inclusive actions that we encourage from contributors to the prokect:
- Try to use gender neutral language when possible. We try and keep a gender neutral to make this project as inclusive as possible. This is to allow for the users to self-identify and feel welcome.
- All disciplines are welcome so we try to refer to "open research" rather than "open science" so that we do not exclude members of the humanities and social sciences from our community.
- This space and project is for all folks interested in making research more reproducible and research software more robust, sustainable, and better. Thus everyone is welcome regardless of their official title and institution affilation.
- Join the discussion in our issues and pull requests.
- You can contact the co-organiser of the project - Tania Allard trallard[at]bitsandchips.me
- You can also contact members of the team through our website.
Git is a really useful tool for version control. GitHub sits on top of Git and supports collaborative and distributed working.
We know that it can be daunting to start using Git and GitHub if you haven't worked with them in the past, but the maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! 💜
In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some instructions to help you get going. Remember that you can ask us any questions you need to along the way.
GitHub has a helpful page on getting started with writing and formatting on GitHub.
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 GitHub 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://https://youtu.be/dQw4w9WgXcQ)) to another webpage.
Also when writing in Markdown, please start each new sentence on a new line. While this formats in the same way as if the new line wasn't included, it makes the diffs produced during the pull request review easier to read! ✨
Before you open a new issue, please check if any of our open issues covers your idea already. If you open a new issue, please follow our basic guidelines laid out in our issue-template. The issue template will automatically be rendered in the comment section of the new issue page, so all you need to do is edit the "Lorem ipsum" sections.
The list of labels for current issues in this repository can be found here and includes:
-
These issues contain a task that a member of the team has determined we need additional help with.
If you feel that you can contribute to one of these issues, we especially encourage you to do so!
-
These issues relate to adding or findind contributors to the project or sprint items
-
Discuss a new project or new topic, these can also be used to discuss new themes for future events and ways to interact with the community
-
Issues related to documenting tools or new processes
-
These issues are suggesting new features that can be added to the project.
If you want to ask for something new, please try to make sure that your request is distinct from any others that are already in the queue. If you find one that's similar but there are subtle differences please reference the other enhancement in your issue.
-
The issue or pull requests needs additional work to be completed Feel free to chip in if you feel like you can contribute to the project or the PR.
-
The work done needs an extra pair of eyes, this can also be a PR awaiting checks before being merged
-
This is a newly proposed project for the hackathon/sprint
Do you have a project in mind to get started? Also feel free to bring existing projects that might need additional help
-
These issues contain a question that you'd like to have answered.
There are lots of ways to ask questions but opening an issue is a great way to start a conversation and get your answer.
-
These issues are actively being worked on
This label is great to identify items you are working on so that we do not stop over each others' toes. As soon as you decide to work on an item assign this label.
-
These items relate to written outputs of the events.
A great way to share the outcomes is by writing success stories or blog posts about the event. Propose a write up using this label.
-
These issues relate to building and supporting the Research software reactor community.
This is all about collaborating, so please let us know how we can best support you as a community member.
-
This issues relate to something that is not quite right or does not work as expected.
We appreciate all contributions to The Research Software Reactor. THANK YOU for helping us build this useful resource. ✨🌟💫
All project management, conversations and questions related to The Research Software Reactor project happens here in the The Research Software Reactor 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 the 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 up front is so useful to everyone involved.
Remember, if you open a new issue, please follow our basic guidelines laid out in our issue-template. The issue template will automatically be rendered in the comment section of the new issue page so all you need to do is edit the "Lorem ipsum" sections.
As soon as you take on a item make sure to add the 
2. Fork the project's repository to your profile
This is now your own unique copy of the project. 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 master repository, otherwise you can end up with lots of dreaded merge conflicts. If you prefer working in the browser, these instructions describe how to sync your fork to the original repository via GitHub.
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 whomever is reviewing your pull request. Help them help you. 😉
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 GitHub 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 GitHub or just want a detailed guide on getting started with version control? Check out our Version Control chapter in The Turing way Book!
4. Submit a pull request
We encourage you to open a pull 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 pull request, you will automatically see the Pull Request Template contents in the pull request body. It asks you to:
- Describe the problem you're trying to fix in the pull request, reference any related issue and use fixes/close to automatically close them, if pertinent.
- List of changes proposed in the pull request.
- Describe what the reviewer should concentrate their feedback on.
By filling out the "Lorem ipsum" sections of the pull request template with as much detail as possible, you will make it really easy for someone to review your contribution!
If you have opened the pull request early and know that its contents are not ready for review or to be merged, add "[WIP]" at the start of the pull 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 pull request to "[Ready for review]".
A member of the 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 GitHub notifications and be prepared to join in that conversation.
You can update your fork of the [repository][alice-dataland-repo] and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review.
You can also submit pull requests to other contributors' branches! Do you see an open pull request that you find interesting and want to contribute to? Simply make your edits on their files and open a pull request to their branch!
GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions 🎈.
The Research Software Reactor project follows the all-contributors specification, so we welcome and recognise all contributions. You can see a list of current contributors here. 😍
The all-contributors bot usage is described here. To add yourself or someone else as a contributor, comment on the relevant Issue or Pull Request with the following:
@all-contributors please add <username> for <contributions>
You can see the Emoji Key (Contribution Types Reference) for a list of valid <contribution> types and examples of how we've run this command in this issue.
The bot will then create a Pull Request to add the contributor and reply with the pull request details.
PLEASE NOTE: Only one contributor can be added with the bot at a time!
Add each contributor in turn, merge the pull request and delete the branch (all-contributors/add-<username>) before adding another one.
Otherwise, you can end up with dreaded merge conflicts.
Therefore, please check the open pull requests first to make sure there aren't any open requests from the bot before adding another.
What happens if you accidentally run the bot before the previous run was merged and you got those pesky merge conflicts?
(Don't feel bad, we have all done it! 🙈)
Simply close the pull request and delete the branch (all-contributors/add-<username>).
If you are unable to do this for any reason, please let us know.
Finally, don't forget to add yourself to the list of contributors here!
These Contributing Guidelines have been adapted from the Contributing Guidelines of the BIDS Starter Kit! and the Turing Way project(License: CC-BY)