FHIR GIT

Intro

This page contains notes/thoughts on how IHE might use GIT to manage the artifacts for our FHIR development. As I write this, I am sure there are things that are just plain wrong. Question everything that is written here. We will eventually need our committee to either bless, delete or tweak these ideas.

Expiration Date

This page expires 2018.12.31. It is intended as a place to gather notes and thoughts. It should go away once we have a clear direction.

Assumptions

1. Readers are familiar with GIT as a mechanism for source code and other file control.
   1. Here is one source of material. Google will identify many more: https://git-scm.com/doc
2. Readers might not be comfortable with using branches within GIT. That should not be an issue at first.
3. Readers might not have used GIT themselves. There are a number of different tools to manage files under GIT, but our readers may not have had the need to use them.
   1. Fear not

Example Repository on GITHUB

I made a repository on GITHUB that is intended to be a sandbox: https://github.com/IHE/fhir

The structure of the repository matches the structure created on the IHE FTP server that John Moehrke created. I entered several versions of the MHD artifacts that John had placed in a separate folder. That means that one can look at this repository and find

1. Current version of each file
2. Prior version of each file
3. Deltas between versions

This is all managed by GIT which does not care about XML, JSON, ... GIT just manages the files as a blob of bytes. It works best for text files (code, xml, json, etc.).

As a further example using this same repository, we can publish a link to a file such as: https://github.com/IHE/fhir/blob/master/StructureDefinition/IHE.MHD.DocumentManifest.structuredefinition.xml. A human could follow that link, find the file and look through the commit history.

Process / Workflows

One Time Setup

The benevolent manager of this effort creates a git repository using our favorite repository provider. The example above uses github. That is my choice, but is not a foregone conclusion.

The folder structure is created at the same time as the initial repository. According to Moore's law, any folder structure one chooses to store files will be found to be unsatisfactory within three months. Changes are possible once in production, but we would have to determine how that alters the downstream work.

A typical GIT practice is to have a master branch that holds the current, blessed content. There is also a develop branch which holds intermediate files. For example, an author is working on a StructureDefinition and wants someone to review it. The author commits the incomplete version to the develop branch and instructs the colleague to retrieve the branch and review. Colleague can edit the file and commit a new version or otherwise communicate with the original author.

<Vassil>I believe for IHE purposes it will be good to have "Release" branches for each release of the framework. A description of a fairly comprehensive use of GIT branches can be found here</Vassil>

Authoring Model 1: GITHUB Based

1. This model uses the web GUI on github. There may be similar capabilities for other repository systems, but I have experience with this one.
2. Author creates initial files on local computer using favorite authoring tool. Suppose for now that is the Forge tool.
3. Author browses to the github repository that was created.
4. Author makes certain to select the develop branch.
5. Author uploads files into the repository using the web browser. Author will be asked to provide comments during the commit process.
6. Benevolent manager reviews the files, merges them into the master branch and completes the publication cycle (more on that below).

Some months pass. Author feels the need to update one or more files. This is not to fix a small bug. This is a change in the design of the resource or something else.

1. As best practice, author should go to the github web site and pull the most recent version of the file(s) from the develop branch. (We can discuss/argue this detail later. Do not get distracted by it.)
2. Author updates the file(s) with their favorite tool again.
3. Author uploads the file modified file to github.
   1. Github will prompt the author for a commit statement to indicate what changed.
   2. We will need to define a template and policy for this. That is not hard.
4. # Benevolent manager reviews the files, merges them into the master branch and completes the publication cycle.

Authoring Model 2: GITHUB Direct

1. The original steps are the same as Model 1.
2. Some months pass.
3. Author sees that the changes to make are very small. The author uses the github web GUI to make the files directly on the develop branch on the github site. Github maintains the tracking information including commits.
4. Benevolent manager reviews the files, merges them into the master branch and completes the publication cycle.

Authoring Model 3: Local GIT Tools

This is the model used by software developers in active, distributed projects.

1. Author uses favorite GIT tool to clone our FHIR repository.
   1. If you do not already have a favorite tool but want to do this, we can make recommendations.
   2. After the clone, the author has a copy of all files on the local system. Included in the collection of files is the history of each file. You have everything.
2. Author will use GIT tool to checkout the develop branch.
3. Author creates new files and/or edits existing files using appropriate tool (Forge, something from Grahame, OxygenXML, vi).
4. Author uses GIT tool to commit changes to local repository and then to push changes to the github repository (develop branch).
5. Benevolent manager .....

Some months pass. Author still has a copy of files on the local computer, but someone else has made changes on the github repository. I think this is a rare case, but I am going to cover it.

1. Author goes to the existing files on local computer and uses a GIT tool to update the local files.
   1. This pulls any changes found on the github repository and merges them into the local files.
   2. If the author has made intermediate changes, those have to be addressed.
2. Author modifies files using favorite tool.
3. Author performs a GIT commit and push on the develop branch to get the github repository updated.
4. Benevolent manager ....

Conflict Resolution

In a software development environment with more than one developer, it sometimes happens that two developers are working on the same file at the same time.

• Developer A commits changes to the file.
• Developer B (who happens to sit next to Developer A but does not talk to Developer A because, you know, developers don't do that) tries to commit the same file to the code repository.
• Git complains and will not let Developer B make the changes to the (github) repository because it sees that Developer A has made changes.
• Developer B has to go through a reconciliation process to get the files in alignment.

The reconciliation process does not involve counseling and is not difficult. When might this happen for us?

1. If two authors are both updating a StructureDefinition or CapabilityStatement. My guess is that this is a rare event as we will likely have a single author working on one resource or a small set of resources.
2. If we have shared code tables, this might be more of an issue. I would submit this is no worse than what we have today with shared files on the FTP server and not knowing if someone is making changes while you decide to do the same.

Document Publication

The sections above discussed the process by which an author produces the artifacts that serve as input to the publication process. Everything discussed above can be performed using software that comes on desktop and laptop computers (web browser, text editor) or software tools that can be downloaded for free. The only caveat to that is the Forge tool is limited to a Windows environment. Tools for managing GIT repositories are available for all platforms.