User Tools

Site Tools


development:ohdsi_github_projects_v2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
development:ohdsi_github_projects_v2 [2016/10/18 19:06]
chrisknoll
development:ohdsi_github_projects_v2 [2016/10/19 18:39]
chrisknoll
Line 1: Line 1:
 OHDSI open-source development best practices (DRAFT) OHDSI open-source development best practices (DRAFT)
 +
 Contributors:​ Anthony Sena, Chris Knoll, Frank DeFalco, Peter Rijnbeek Contributors:​ Anthony Sena, Chris Knoll, Frank DeFalco, Peter Rijnbeek
  
Line 13: Line 14:
  
 http://​forums.ohdsi.org/​c/​developers http://​forums.ohdsi.org/​c/​developers
 +
 +==== Contributing code ====
 +If you decide that you'd like to contribute code to OHDSI, the following sections will provide you with approaches for making contributions. Throughout this section, we'll refer to two distinct groups: **internal collaborators** and **external collaborators**. The difference between these groups is centered around their access to the repository. **Internal Collaborators** have rights to merge and push their changes directly into the repository while **external collaborators** do not. External collaborators must fork a repository in order to do their work and submit a pull request. This [[http://​stackoverflow.com/​questions/​3611256/​forking-vs-branching-in-github|Stack Overflow Article]] provide an explanation with supporting details.
 +
 +Whether you are an internal or external collaborator,​ the process of contributing changes is the same:  you clone the repository, create a branch, make your changes, and submit a pull request. ​ The information presented here will be equally valid from either perspective because the steps of branching and pull requests are the same for both groups. The main difference is which repository the collaborator will be branching from: the OHDSI repository or a private fork of the repository.
 +
 +==== Code Management ====
 +
 +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. ​
 +
 +=== Forking and Cloning ===
 +
 +In order to begin working on OHDSI code, you will either need to clone a repository (repo) either directly from OHDSI or from a fork of an OHDSI repo.  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 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).
 +
 +=== Working with a repository ===
 +
 +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:
 +
 +<​code>​
 +$ cd C:\git
 +$ git clone "​https://​github.com/​{owner}/​{RepoName}.git"​
 +</​code>​
 +
 +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 branches in a later section.
 +
 +An additional step for **forked repositories**: ​ In order to remain in sync with the original repository (the one that was forked from), a special remote reference will be needed in order to grab the new changes in the '​upstream'​ repository into the forked repository. ​ We will get into the details of this remote reference in the section for syncing upstream changes, but this is the command that should be executed to add the upstream reference to your forked repo (from [[https://​help.github.com/​articles/​configuring-a-remote-for-a-fork/​|Configuring a remote for a fork]] in GitHub help):
 +
 +<​code>​
 +$ git remote add upstream https://​github.com/​ORIGINAL_OWNER/​{RepoName}.git
 +</​code>​
 +
 +We will describe this '​upstream'​ remote in the later section '​Getting Changes'​
 +
 +=== Viewing the repository history ===
 +
 +To see the history in the repo, you can use any of the following commands:
 +
 +<​code>​
 +$ git log
 +$ git log --graph
 +$ gitk
 +</​code>​
 +
 +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!
 +
 +
 +=== Working in branches ===
 +
 +When you want to add a new feature or contribute a fix, you will always start by creating a branch. ​ To see the list of branches in the repository:
 +
 +<​code>​
 +$ git branch
 +</​code>​
 +
 +You will see something similar to the following:
 +
 +<​code>​
 +$ git branch
 +Branch 1
 +Branch 2
 +(*) master
 +</​code>​
 +
 +The asterisk will provide you with an indicator of your current branch which in this case is "​master"​. The "​master"​ branch is, by convention, the main branch where the most stable code will live. It is no different from any other branch except that is never removed. ​
 +
 +Let's start by creating a new branch for our work by issuing the command:
 +
 +<​code>​
 +$ git checkout -b "​new-feature-branch"​
 +</​code>​
 +
 +You'll then see the following: ​
 +
 +<​code>​
 +$ git checkout -b "​new-feature-branch"​
 +Switched to a new branch '​new-feature-branch'​
 +</​code>​
 +
 +Git has created a new branch called "​new-feature-branch"​ and made it your active branch. You can verify this by running the git branch as we did above
 +
 +<​code>​
 +$ git branch
 +Branch 1
 +Branch 2
 +master
 +(*) new-feature-branch
 +</​code>​
 + 
 +Now you can begin working by adding new commits to the repository. The new commits will be only visible in the '​new-feature-branch'​. ​ These commits are merged into the '​master'​ branch via Pull Requests.
 +
 +=== Committing changes ===
 +
 +As you develop your code, you will be changing files and adding them to the repository by using the "​commit"​ command. If you'd like to commit all of your changed files, you can do this by issuing the following command:
 +
 +<​code>​
 +$ git commit -a -m "<​commit message>"​
 +</​code>​
 +
 +This is a good option if you know all your changed files relates to a single feature or bug-fix. ​ However, if you want to divide commits into separate logical units you can perform the following steps:
 +
 +<​code>​
 +$ git add {file 1}
 +$ git add {file 2}
 +$ git add {file 3}
 +$ git commit -m "Fixes #125"
 +$ git add {file 4}
 +$ git add {file 5}
 +$ git add {file 6}
 +$ git commit -m "Fixes #128"
 +</​code>​
 +
 +The above adds file 1, file 2 and file 3 into one commit, and file 4, file 5 and file 6 into a second commit, each commit having a different message. ​ This is sometimes useful in order to organize your commits into logical pieces.
 +
 +
 +=== Pushing Changes and Pull Requests ===
 +
 +Once you have completed your local changes, you will want to submit them for inclusion in the main repository.
 +
 +First, you will need to "​push"​ your changes from your local repository to your remote repository using the "git push" command:
 +
 +<​code>​
 +$ git push -v origin --all
 +</​code>​
 +
 +This will make your branch available on GitHub as a source for a pull request.
 +
 +GitHub has an [[https://​help.github.com/​articles/​about-pull-requests/​|excellent]] article on initiating pull requests. Please refer to this article for detailed instructions. ​ The important item to note is: when creating the pull request, the **base** will be set to the repository'​s branch that you wish to contribute to, and the **head** branch will the the branch that your contributions were made.  ​
 +
 +If you wanted to contribute your commits from '​new-feature-branch'​ in your repository, you would navigate to your branch in GitHub, click New pull request, and then chose the target repository (OHDSI/​Atlas for example) and the branch to apply your commits to (usually '​master'​). ​ The only difference between an internal collaborator Pull Request and an External Collaborator Pull Request is that the Internal Collaborator will be making a pull request between 2 branches within the OHDSI repository, and the External Collaborator will be making a pull request between the branch in the External Collaborator'​s fork and the branch in the OHDSI repository. ​ Otherwise, it is exactly the same process.
 +
 +
  
  
  
development/ohdsi_github_projects_v2.txt ยท Last modified: 2017/02/02 14:41 by chrisknoll