{"type":"doc","content":[{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"bd19060d-1121-44b0-bc44-437a0c290d78"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The OpenMRS community is currently in the process of evaluating Git as a replacement for SVN.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"GitHub","type":"text"}]},{"type":"paragraph","content":[{"text":"There is an ","type":"text"},{"text":"OpenMRS organization","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs"}}]},{"text":" on GitHub (","type":"text"},{"text":"http://github.com/openmrs","type":"text","marks":[{"type":"link","attrs":{"href":"http://github.com/openmrs"}}]},{"text":") used to host community OpenMRS projects. All bundled modules managed within git are kept under this organization with the naming convention \"openmrs-module-","type":"text"},{"text":"","type":"text","marks":[{"type":"em"}]},{"text":"\". 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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Naming Conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"When using Git for your project, please use the following naming conventions:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use all lowercase.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For modules, use the name \"openmrs-module-","type":"text"},{"text":"moduleid","type":"text","marks":[{"type":"em"}]},{"text":"\" (for example: ","type":"text"},{"text":"openmrs-module-htmlformentry","type":"text","marks":[{"type":"code"}]},{"text":"); for contributions, use the name \"openmrs-contrib-","type":"text"},{"text":"contribname","type":"text","marks":[{"type":"em"}]},{"text":"\" (for example: ","type":"text"},{"text":"openmrs-contrib-standalone","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Please include \"OpenMRS module\" or \"OpenMRS Contrib\" somewhere in your project's README.","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"When creating a new module or contrib, please e-mail ","type":"text"},{"text":"code@openmrs.org","type":"text","marks":[{"type":"link","attrs":{"href":"mailto://code@openmrs.org?subject=Module%20ID%20request"}}]},{"text":" to request a module ID or contribution name, including your ","type":"text"},{"text":"OpenMRS ID","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/pages/createpage.action?spaceKey=RES&title=OpenMRS%20ID"}}]},{"text":", 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.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Getting Started with GitHub","type":"text"}]},{"type":"paragraph","content":[{"text":"To get started with Git and GitHub you should read the documentation for your OS:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://help.github.com/mac-set-up-git/","type":"text","marks":[{"type":"link","attrs":{"href":"http://help.github.com/mac-set-up-git/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://help.github.com/win-set-up-git/","type":"text","marks":[{"type":"link","attrs":{"href":"http://help.github.com/win-set-up-git/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://help.github.com/linux-set-up-git/","type":"text","marks":[{"type":"link","attrs":{"href":"http://help.github.com/linux-set-up-git/"}}]}]}]}]},{"type":"paragraph","content":[{"text":"These pages explain adding SSH keys (better than passwords), and configuring your local git to use your GitHub credentials, e.g.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"\ngit config --global github.user username\ngit config --global github.token 0123456789yourf0123456789token\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Repository conversion","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"tool that Github recommends","type":"text","marks":[{"type":"link","attrs":{"href":"http://help.github.com/import-from-subversion/"}}]},{"text":" is ","type":"text"},{"text":"svn2git","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/nirvdrum/svn2git"}}]},{"text":". It expects your project to be organized in the standard SVN way of ","type":"text"},{"text":"trunk","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"branches","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"tags","type":"text","marks":[{"type":"em"}]},{"text":", so you should reorganize the project before conversion if necessary.","type":"text"}]},{"type":"paragraph","content":[{"text":"Copy the list of authors from ","type":"text"},{"text":"Github Authors txt","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25520562"}}]},{"text":" into an authors.txt file and from that folder, start with:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ mkdir openmrs-module-yourmoduleid\n$ cd openmrs-module-yourmoduleid\n$ svn2git http://svn.openmrs.org/openmrs-modules/yourmoduleid --authors ~/authors.txt","type":"text"}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"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).","type":"text"}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"paragraph"},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ svn log --quiet | grep \"^r\" | awk '{print $3}' | sort | uniq","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"dev mailing list","type":"text","marks":[{"type":"link","attrs":{"href":"http://go.openmrs.org/dev"}}]},{"text":" and ask for help). ","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"NB Other alternatives to svn2git include;","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"svn-git","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":" Git comes with a pre-installed tool called ","type":"text"},{"text":"svn-git ","type":"text","marks":[{"type":"strong"}]},{"text":"see ","type":"text"},{"text":"https://aboullaite.me/migration-from-svn-to-git-a-developer-guide/","type":"text","marks":[{"type":"link","attrs":{"href":"https://aboullaite.me/migration-from-svn-to-git-a-developer-guide/"}}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"svn2git","type":"text","marks":[{"type":"strong"}]},{"text":" is just a wrap up tool around git's ","type":"text"},{"text":"svn-git , ","type":"text","marks":[{"type":"strong"}]},{"text":"and it makes using ","type":"text"},{"text":"svn-git","type":"text","marks":[{"type":"strong"}]},{"text":" more easier and flexible .However in some cases , it may be better to use svn-git directly","type":"text"}]},{"type":"paragraph","content":[{"text":" 2. ","type":"text"},{"text":"The github Importer","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":" The github Importer is also a great and easy to use tool to use for conversion and migration of repos from svn to git","type":"text"}]},{"type":"paragraph","content":[{"text":" see ","type":"text"},{"text":"https://help.github.com/en/articles/importing-a-repository-with-github-importer","type":"text","marks":[{"type":"link","attrs":{"href":"https://help.github.com/en/articles/importing-a-repository-with-github-importer"}}]}]}]},{"type":"paragraph","content":[{"text":"Once the complete project is converted from svn to git format, you need to get it up to GitHub.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create a new repo in Github (or ask for one for the OpenMRS org from code@openmrs.org)","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Name: openmrs-module-yourmoduleid","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Description: a one-line description of what the module does (look at others for examples)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Make it public","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Initialize with a README","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add .gitignore for maven","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Edit the module's pom.xml to use the github address","type":"text"}]},{"type":"codeBlock","content":[{"text":"\t\n\t\tscm:git:https://github.com/openmrs/openmrs-module-yourmoduleid/\n\t\tscm:git:https://github.com/openmrs/openmrs-module-yourmoduleid/\n\t\thttps://github.com/openmrs/openmrs-module-yourmoduleid/\n\t","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Change the local repo you just converted to point at that one github repo \"origin\" (below)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ git remote add origin https://github.com/openmrs/openmrs-module-yourmoduleid.git","type":"text"}]},{"type":"paragraph"},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ git pull origin master","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Assuming that your module uses the OpenMRS license and it wasn't already in subversion's root, add it:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"wget https://raw.github.com/openmrs/openmrs-core/master/license.txt","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Commit your changes locally","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ git add .\n$ git commit -m \"migrating from svn to github\"","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Push the code to github (below)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ git push","type":"text"}]},{"type":"paragraph","content":[{"text":"Push the tags manually using the following command.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ git push --tags","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add default teams to the new github repository:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Full Committers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Partial Committers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Repo Owners","type":"text"},{"type":"hardBreak"},{"text":" ","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Retiring the SVN project","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add a text file called","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"MIGRATED","type":"text","marks":[{"type":"em"},{"type":"strong"}]},{"text":" to the SVN project root that contains the URL of the new repository location (","type":"text"},{"text":"example","type":"text","marks":[{"type":"link","attrs":{"href":"https://svn.openmrs.org/openmrs-modules/logmanager/MIGRATED"}}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove trunk and branches folders","type":"text","marks":[{"type":"strong"}]},{"text":" (previous tags may be left in SVN)","type":"text"}]}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"# If you just completed running svn2git, start by stepping out of the git repo\n$ cd ..\n\n\n# Check out the top of the svn project\n$ svn co https://svn.openmrs.org/openmrs-modules/yourmoduleid --depth=immediates\n$ cd yourmoduleid\n\n\n# Add a MIGRATED file and remove trunk & branches folders\n$ echo \"https://github.com/openmrs/openmrs-module-yourmoduleid/\" > MIGRATED\n$ svn add MIGRATED\n$ svn rm trunk\n$ svn rm branches\n\n\n# Commit changes to subversion\n$ svn commit -m \"migrated to github\"","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"As a courtesy, please notify OpenMRS developers with an e-mail to the developers mailing list (","type":"text"},{"text":"example","type":"text","marks":[{"type":"link","attrs":{"href":"https://groups.google.com/a/openmrs.org/d/topic/dev/_9CShefSY44/discussion"}}]},{"text":").","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mavenization","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"Converting old code to Maven","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25520857"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"For Mavenized projects, IDE specific files should not be included in the repository. Git supports an ignore file similar to SVN called ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"em"}]},{"text":", and so for a typical mavenized module project this will look like:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n.classpath\n.idea\n.project\n.settings/*\napi/.classpath\napi/.project\napi/.settings/*\napi/target/*\nomod/.classpath\nomod/.project\nomod/.settings/*\nomod/target/*\n","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"this page","type":"text","marks":[{"type":"link","attrs":{"href":"http://help.github.com/remove-sensitive-data/"}}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"\n# Remove all JAR references from current branch history\ngit filter-branch --index-filter 'git rm --cached --ignore-unmatch *.jar'\n\n# Push to origin repo\ngit push origin master --force\n\n# Cleanup local objects\nrm -rf .git/refs/original/\ngit reflog expire --expire=now --all\ngit gc --prune=now\ngit gc --aggressive --prune=now\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Your pom.xml file also needs updated to refer to github instead of svn in the \"scm\" tags.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Authors","type":"text"}]},{"type":"paragraph","content":[{"text":"During the conversion, user accounts for the OpenMRS SVN repository can be mapped to personal GitHub accounts. This is done using a text file which lists account mappings as follows:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\njohnd = John Doe \n","type":"text"}]},{"type":"paragraph","content":[{"text":"If authors list is not specified all the authors email id's will be randomly generated with the git hashes. The following command can generate a list of SVN accounts from an existing SVN repository:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$ svn -q log http://svn.openmrs.org/openmrs-modules/YOURMODULE | grep -E \"r0-9+ | .+ |\" | awk '{print $3}' | sort | uniq > ~/authors.txt","type":"text"}]},{"type":"paragraph","content":[{"text":"We have a shared authors file. Please use and add to this as needed: ","type":"text"},{"text":"Github Authors txt","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25520562"}}]},{"text":"!","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"IDE integration","type":"text"}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"include","parameters":{"macroParams":{"":{"value":"Git IDE Integration"}},"macroMetadata":{"macroId":{"value":"94c0d12f-2310-413b-948f-fcc3c00dc84a"},"schemaVersion":{"value":"1"},"title":"Include Page"}}}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"Here's the set of ","type":"text"},{"text":"best practices","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/dchelimsky/rspec/wiki/Topic-Branches"}}]},{"text":" to follow in distributed OpenSource projects.","type":"text"}]}],"version":1}

Browser not supported