Observational Health Data Sciences and Informatics

For reference, we reviewed some common release/code management articles such as Gitflow and alternatives to form the basis of this article. The goal with this approach was to keep the code management process as simple as possible while leveraging the functionality available in Git and GitHub. We've also formally adopted the semantic versioning scheme for all software which is already in practice in most of the OHDSI code repositories.

This article assumes you have familiarity with Git and GitHub. If you do not, here is a nice collection of guides to get you started:

https://help.github.com/articles/good-resources-for-learning-git-and-github/

For the purposes of this article, we assume that you have installed Git and have access to a Git repository. You can set up your own Git repository to follow along with the examples in this article. As a note, all of the code in this article is using the Git command line on Windows. There should be no material difference between running Git commands on Windows versus another operating system but if you do experience any problems please report them on the OHDSI forum:

http://forums.ohdsi.org/c/developers

The following section is described how to work with source code in a Git repository. It provides a general overview of using Git and explains how to provide code contributions. Subsequently, the Release Management section will focus on best practices and conventions for controlling versions and releases of the source code in a repository.

In order to begin working on OHDSI code, you will either need to clone a repository (repo) either directly from the OHDSI or from a fork that you create. If you do not have permissions to push changes into a repo (which is usually the case when you are an external collaborator), then you can go to the main OHDSI repository site (example: https://github.com/ohdsi/atlas) and click the Fork button in the top right area of the screen. This will create a copy of the repository under your own user repository in GitHub. For example, if you were to fork https://github.com/ohdsi/atlas, it would create the new repository under https://github.com/{your github user}/atlas. You have full permissions to commit changes to the personal repo you forked, and can submit ehancements to the OHDSI repo via pull requests (discussed later).

Once you know the repository you want to work on (either a fork or directly in the OHDSI repo), you will then need to clone it locally. Create a directory that you'd like to use to store your Git code (i.e. C:\Git). Then using the Git command line, navigate to the directory you created and clone a repository using the following command:

cd C:\git
git clone "https://github.com/{owner}/{RepoName}.git"

This will create a directory {RepoName} under the directory you executed the git command (in this example, C:\Git). This will also copy down the repo contents, and set your active branch to 'master'. We will talk about branching in a later section.

To see the history in the repo, you can use any of the following commands:

$ git log
$ git log --graph
$ gitk

gitk will launch a UI that let's you see the commits in a visual graph and is the recommended commit history viewer.

If everything looks good, then congratulations! You have cloned your repository and are ready to contribute!