Hello and welcome to the ACHDS guidebook project! 🎉
The guidebook is written as a series of linked markdown files. Here is the first page.
Our goal is to develop data and coding standards that we encourage ACHDS team members to follow, to enable us to collaborate and create reproducible research.
We would like all current members of the team to contribute. Please read through the contributing guidelines below, and get in touch with Dimitra if you have any questions 😃
This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to Dimitra.
Before you start: set up Github account
Please set up a free GitHub account and sign in. Here are some instructions. Let us know you've done this so we can add you to the ACHDS organisation.
1. Decide on how you'd like to contribute
This is a collaborative project, so the best way to figure out how to contribute is by taking part in team discussions 😃 Join the weekly lab meeting (Thursdays at 14:05), or add your thoughts to one of the Health Data Lab MS Team channels. (If you are a member of ACHDS but don't have access to the Health Data Lab team, let us know to add you.)
There are a few ways to contribute:
- Create a new chapter
- For this, you need to create a new .md file, and link to it from the index page and from the previous chapter
- If you want to add a chapter in the middle of the guidebook, you'll need to change the "previous" link for the following chapter
- Add more details to an existing chapter
- Correct typing mistakes or make other small improvements to the text. You can do this by editing the existing chapter .md files.
You might also just like to suggest improvements to the guidebook, but not make the changes yourself. This is also very welcome! In this case, you just need to do step 2 below: add an issue describing your suggested improvement.
2. Add an issue describing your suggested contribution (or assign an existing issue to yourself)
Once you've identified a way to contribute, please let us know what you're planning to do by adding a new issue here, or assign an existing issue to yourself. Issues are basically tasks that we want to achieve, so by adding your issue to the list we can keep track of who is working on what.
Please don't skip this step, as knowing what you're planning on doing in advance ensures 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. Here is more information about Github issues.
3. Create a new branch (and give it a name associated with the issue)
Using a separate branch allows you to isolate development work without affecting other branches in the repository. Please note that you need to make an initial commit in order to start a new branch on GitHub. This should be a small initial change (e.g. add a single sentence), that you follow by creating a draft pull request (step 4 below). Then you can keep making changes to your branch (step 5) for as long as you like. But by opening the draft pull request as early as possible in your workflow, it makes it clear to everyone in the team that you are working on the associated issue.
4. Create a draft pull request and add "closes #[issue number]" in the description
A pull request is the method by which you let us know of the contribution you are working on. Adding "closes #[issue number]" in the description links the pull request to the issue. This shows that work is in progress to address the issue, and it automatically closes the issue when the pull request is merged.
5. Go ahead and make your changes to your branch
Make sure you commit your changes frequently, and use good commit messages that briefly describe the changes you made.
6. Change the draft pull request to "ready for review"
When you are ready to get feedback from other team members, change the draft pull request to ready to review. You can ask specific team members to review your changes.
7. Merge the pull request
When you get approval from the reviewer, merge the pull request and delete the branch (this closes the issue). It doesn't matter who merges the pull request (you or the reviewer), but successfully merging your changes is a satisfying action, so we recommend that you do it yourself - you've earned it after all your hard work. Well done!! 🎈🎈🎈 And thank you 😃