Get Started with FHIR on GitHub

Starting on September 7, 2018, the core development of the FHIR specification is moving from GForge/svn to GitHub. The subversion repository will become read-only on September 7, and the GitHub repository will be available for writes by September 10. If you've been committing to the specification via svn, here's what you need to know about the transition. Please note that over time, we'll be looking at better ways to incorporate code review and approvals as steps in the process of developing the specification, especially to protect normative content from undesired changes. For now, though, we're adopting the committers model we had in svn, where community members agree to a set of common standards about when and how edits can be made.

Get Started with git, GitHub, and the FHIR Spec

1. Please sign up for GitHub and let us know your GitHub username so we can ensure you're a member of the right teams (i.e., so we can give you the permissions you need to commit). To do this, just send a message to the "GitHub Usernames" stream of #committers listing your username. For example, my message just says "I'm jmandel". (Pro tip: put your username between back-quotes to format it with a monospace font.)

2. Download and install a git client for your operating system. There are myriad clients available, each with different selling points — but for consistency, the instructions here will assume you're installing the standard, open-source git command-line client. For details on how to get started, follow the instructions at https://git-scm.com/book/en/v2/Getting-Started-Installing-Git.

3. Clone the FHIR specification from GitHub by browsing to https://github.com/hl7/fhir, and choosing "Clone or download". You can clone using HTTPS, in which case you'll need to enter your username and password each time you connect; or you can set up ssh keys to automatically authenticate (details here).

Submit changes to the FHIR spec by pushing from a local clone

Now that you have a local clone of the FHIR spec, you can get to work making the spec better :-) Here, we'll work through a quick example of how to submit a change.

1. Make sure you're up to date with the latest master branch for the FHIR spec as a starting point for your changes. I can make sure I'm on the master branch via git checkout master and make sure I'm up to date with the latest via git pull.

2. Create a local branch for your work, with a descriptive name. A best practice is to prefix your branches with your github username. So for example if I wanted to propose an update to FHIR's history.html page to indicate the move to github, I might do git checkout -b jmandel-history-with-git to create a branch named jmandel-history-with-git where I'll be doing my work.

3. Next, edit the files you need to edit; in my case, I might use a text editor to make these changes, so I'd run something like vim source/history.html to make and save my changes.

4. Now, review your changes. To see what files have changed, you can run git status; to see a diff you can run git diff. A full tutorial on git is beyond the scope of this guide, but https://git-scm.com/book/en/v2 provides an excellent starting point.

5. Run the FHIR build tool to make sure you haven't inadvertently introduced any errors in the process of your edits. The full detail on getting set up are available at https://confluence.hl7.org/display/FHIR/FHIR+Build+Process — but if you've previously been making commits to FHIR via subversion, you should be all set up and you can just run ./publish.bat (in Windows) or ./publish.sh (in Mac or Linux).

6. If everything looks good, you can commit your work. First, add any files that need to be committed via git add. (In the case of this example, I'd do git add source/history.html. Pro tip: use git status to see what files have changed) Then you can git commit to commit your changes. You'll be prompted for a commit message, who should be a short, descriptive explanation of the changes you've made. You can also supply this message directly via the -m flag, so in this example I might do git commit -m "Add GitHub links to history.html"

7. Make sure that the main branch has not been updated in the meantime, by repeating step 1.

8. Merge the main branch into your feature branch name: git checkout feature_branch_name (in this example, that'd be git checkout jmandel-history-with-git), followed by git merge master. If you encounter conflicts, these must be resolved.

9. Repeat step 5, running the FHIR build tool, to make sure the merge from step 8 was successful.

10. If everything looks good, you can push your changes up to GitHub via git push -u origin feature_branch_name. (In this example, that'd be git push -u origin jmandel-history-with-git).

11. Create a "Pull Request" in GitHub to get your changes merged. To do this you can browse to https://github.com/hl7/fhir where you should see your recent change flagged at the top of the screen with a "Create pull request" button. (If not, just click "New pull request" and choose your newly pushed branch as the "compare:" branch.

12. Once you complete the request by clicking the green "Create pull request" button, you'll see that status checks are pending. These status checks ensure that your branch is up-to-date and that your proposed changes have not introduced any build errors. (Behind the scenes, the FHIR build tool's publish.sh is running on a cloud server, just as it did on your local machine in step 5 to check for errors.)

13. Once status checks have completed without errors, you will be able to merge your pull request into the master branch. Just after you merge, you can click "Delete" in GitHub to delete your now-merged branch.

Quick-fix typos by direct edits in GitHub's UI

For a truly tiny specification change, like correcting a simple typo, it's possible to complete the editing and pull request process from directly within the web browser.

1. Navigate to a page that has a typo, like https://github.com/hl7/fhir/blob/master/source/history.html. Then click the pencil icon ("edit this file") and make changes inline.

2. At the bottom of the screen, add a description outlining your changes, and choose "Create a new branch", giving it a descriptive name. A best practice is to prefix your branches with your github username. So for example if I wanted to propose an update to FHIR's history.html page to correct a spelling error, I might name the branch jmandel-history-typo.

3. Complete the form by clicking "Create pull request", following the instructions starting at step 9 in the detailed outline above.