OpenMRS resources

What is OpenMRS?

OpenMRS is an open-source electronic medical records platform often used in developing countries. ThoughtWorks contributes to it as part of their Humanitarian Software Program.

It might look like there's an intimidatingly large amount of stuff to do below, but

• you only have to set things up once!
• it'll be second nature to you in no time
• learning this workflow will serve you very well when contributing to other open source projects, or even just working on a team of software engineers.

Here is a screenshot! (please ignore the French)

Relevant Links

Here are all the relevant links for future use:

• Developer's Guide

• Google Drive with VMs Just download OpenMRS.tar.gz

• Wintersession Presentation

• OSAP wiki (which has even MORE links!)
• Background OpenMRS reading (more links to check out in your free time)

• Official OpenMRS getting-started guide (we don't really use this)
• Useful getting-started guide with explanation of manual setup
• VM setup

• Git + workflow tutorial
• Running the webapp and viewing changes in code

Git setup

See here. (Not necessary for Full Virtual Machine Setup)

OpenMRS setup

It's highly recommended you choose one of the VM based setups. If that's not possible (often because of memory constraints) or if you'd simply prefer to do the manual setup, follow the guide here: https://wiki.openmrs.org/display/docs/Getting+Started+as+a+Developer and make sure to talk to Chris, Katherine, and/or Vibhaa about this setup.

1) Full Virtual Machine Setup (Recommended)

• This setup uses a virtual machine that has the full OpenMRS setup already configured for you. You would be working within the virtual machine to both write code and to run/test it. Features snapshots of the VM that allow you to very easily rewind to a previous state.
• Pros: Quick and easy to do. You only need to install VirtualBox and download the VM to work on the project.
• Cons: Might be sluggish if you don't have enough RAM.
• Requirements: 7GB hard disk space and 3GB RAM (preferably 4+GB). Requires you to install VirtualBox and to download/copy over the VM.

Installation: Download and install VirtualBox. Download the Virtual Machine (the OpenMRS.tar.gz file). Then extract the folder from this link. Add the downloaded machine in VirtualBox (Machine->Add Machine and navigate to the OpenMRS.vbox file within the folder extracted from the VM link). Install the VirtualBox Extension Pack from the previous VirtualBox link. If working on the sample bug, click on snapshots in the top right of the VirtualBox window and restore the top snapshot. Then just run the machine and begin!

2) Partial Virtual Machine Setup

• This quick setup allows you to communicate with a virtual machine (VM) that has all OpenMRS related setup requirements already installed. You will be working in your machine and running/testing the code by using the command line to control the VM.
• Pros: Allows you to use your preferred text editor/work environment.
• Cons: Less intuitive of what's going on unless you are very comfortable with working from the command line.
• Requirements: 10GB of hard disk space and 3GB RAM. Requires you to install VirtualBox and Vagrant.
• Once VirtualBox and Vagrant are installed, follow the rest of the setup in the README here: https://github.com/cpschuster/OpenMRS-dev-setup/tree/express-setup . Issue this command to clone it to your machine:

  git clone -b express-setup https://github.com/cpschuster/OpenMRS-dev-setup   

Then come look for Danni or Nicole to get a flash drive to load the VM more quickly!!!! Then follow the "Happy Path Usage Instructions" in the README at https://github.com/cpschuster/OpenMRS-dev-setup/tree/express-setup

Note: If you've ever used the express setup before, you'll want to do

  vagrant box remove OpenMRS-dev-setup-clone 

before issuing "vagrant up".

3) Manual Setup

• This setup fully configures your machine to be able to contribute to OpenMRS.
• Pros: Lowest hardware requirements.
• Cons: Slowest and most error prone setup (especially if you run Windows)

Sample Bug Walkthrough

Before working on a current bug, you might like to try completing the walkthrough of this older one in order to get a feel for the workflow.

General Workflow

git: version control system.

GitHub: visual interface for git. Lets you view repositories, pull requests (requests from other people to add original code), etc. online.

• First, fork the "official version" from GitHub to your own Github repository (happens only once). Here's the offical code base: https://github.com/openmrs/openmrs-core
• Set up your remotes so you get new code and push your original code to the right places (setting an "origin" remote for your fork and an "upstream" remote for the official code base)
• Pull new changes from the the "upstream" remote
• Make a new branch for the ticket you'd like to work on
• Make local changes on your machine to fix the bug/implement the feature
• Push to your "origin" remote
• When done, make a pull request on upstream, which will be reviewed. Current OpenMRS pull requests
• Repeat
• Hopefully get your pull request merged into upstream! Looks like this.

See here for a more detailed walkthrough.

New Beginner Tickets

Pair programming is great!

If you're working on one of these, please tell Chris, Katherine, and/or Vibhaa (or edit the wiki and add your name next to it).

• TRUNK-3274 Voided person addresses and names should be ignored by the short patient form validator
• TRUNK-2941 Find+Move mediawiki archive pages in confluence
• TRUNK-209 MRNgen Duplicate Global Properties 1
• TRUNK-3638 Separate liquibase file into separate files per version
• TRUNK-3657 Delete clob data storage when deleting a form resource
• TRUNK-4575 TestData - Duration Unit not usable
• TRUNK-3746 Error adding a ConvSet in a second form schema
• TRUNK-4473 Form Resource (Long-Text) causes error with binary file upload

List of all intro tickets:

• https://tickets.openmrs.org/secure/IssueNavigator.jspa?mode=hide&requestId=10068