The OpenMRS community is currently in the process of evaluating Git as a replacement for SVN.

GitHub

There is an OpenMRS organization on GitHub (http://github.com/openmrs) used to host community OpenMRS projects. All bundled modules managed within git are kept under this organization with the naming convention "openmrs-module-<moduleid>". All community-supportes modules are welcome and encouraged to be kept under the OpenMRS organization as well. Other organizations and authors who maintain OpenMRS modules under other accounts within github are encouraged to use the same naming convention.

Naming Conventions

When using Git for your project, please use the following naming conventions:

Use all lowercase.

For modules, use the name "openmrs-module-moduleid" (for example: openmrs-module-htmlformentry); for contributions, use the name "openmrs-contrib-contribname" (for example: openmrs-contrib-standalone).

When creating a new module or contrib, please e-mail ﻿code@openmrs.org to request a module ID or contribution name, including your OpenMRS ID, a description of your module/contribution, and your proposed module ID or contribname. The conversation with the "code" e-mail group is used to avoid duplicates and maximize consistency of naming; you should expect a module ID to be decided within one day of your request. Eventually, we hope to create a more automated process for ensuring uniqueness of module identification & awareness of existing modules.

Getting Started with GitHub

To get started with Git and GitHub you should read the documentation for your OS:

Repository conversion

The tool that Github recommends is svn2git. It expects your project to be organized in the standard SVN way of trunk, branches and tags, so you should reorganize the project before conversion if necessary.

Copy the list of authors from ﻿Github Authors txt into an authors.txt file and from that folder, start with:

Be patient. The svn2git command can run for a while without any visual feedback. You can open another terminal and peek at the contents of the directory (most initial content goes into the .git folder which is hidden by default).

If you get an error from svn2git, it's possible that one or more users are missing from the authors.txt file. Checkout a local copy of the module from svn and list out all authors who contributed to the module:

$ svn log --quiet | grep "^r" | awk '{print $3}' | sort | uniq

Make sure each of these users has an entry in the authors.txt file. If anyone is missing, then find their corresponding git name and e-mail (if you cannot find these, e-mail the dev mailing list and ask for help).

Once the complete project is converted from svn to git format, you need to get it up to GitHub.

Create a new repo in Github (or ask for one for the OpenMRS org from code@openmrs.org)

Name: openmrs-module-yourmoduleid

Description: a one-line description of what the module does (look at others for examples)

Under the Admin section for the new github repository, make sure Wiki & Issues are unchecked (we don't want wiki & issues going into github; rather, we want people using wiki.openmrs.org and jira.openmrs.org)

Retiring the SVN project

It's important to clearly indicate to other developers that the SVN project is no longer the active repository for the project. After successfully loading the code into github, rather than delete the project, you should:

Add a text file calledMIGRATED to the SVN project root that contains the URL of the new repository location (example)

Leaving the root folder with a MIGRATED text file pointing to the new location will allow any persons with old links to find the new location of the code.

As a courtesy, please notify OpenMRS developers with an e-mail to the developers mailing list (example).

Mavenization

It's preferable that older modules be mavenized prior to migrating to git, since it significantly reduces the size of the repository, making it easier for low-bandwidth developers to clone the repository locally. If your module is not yet mavenized, see ﻿Converting old code to Maven.

For Mavenized projects, IDE specific files should not be included in the repository. Git supports an ignore file similar to SVN called .gitignore, and so for a typical mavenized module project this will look like:

Mavenized projects do not include JAR files, but if your project was previously a normal project with JAR files, then these will still exist in the repository history, and will make your new Git repository much larger than it needs to be. However JAR files can be removed from the history of a project using the method described on this page:

Once you've cloned the repository, skip the rest of the import because you want to import this as a Maven project

To import as a Maven project:

Select File->Import

Select Maven->Existing Maven Projects

Select the project to import

To associate this project with Git:

Right click on project and select Team->Share Project

Select Git

Check "Use or create repository in parent folder of project"

If the HOME environmental variable is not set it will give warning:The following directory will be used for GIT user configuration and as a default repository location. If it is your home directory (e.g. C:\Users\Tom) click OK or create the HOME environmental variable pointing to your home directory and restart Eclipse.

Maven SCM Connector for Git (available from Eclipse Marketplace)

Doesn't create an EGit managed project

NetBeans

Support through plugin

IntelliJ IDEA

Built-in support for Git and GitHub

Best Practices

Here's the set of best practices to follow in distributed OpenSource projects.

Looks like $GIT-SVN does the same thing as $svn2git which may require to be separately installed.

Executing for-example $git svn log may result into: Can't locate SVN/Core.pm in @INC (you may need to install the SVN::Core module) (@INC contains: as can be seen at: http://pastebin.com/dL26t91e which is fixed by making some links, however am yet to be sure which directories to link together in this (stack trace) case

Having looked around to solve the above issue, i have found no solution and so i switched to ubuntu where $GIT-SVN was not able to create the directory content though it could set up the git folder pretty well, $svn2git does it better