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)

Developer's Guide

Google Drive with VMs Just download OpenMRS.tar.gz

Wintersession Presentation

What to install before the workshop

If your computer has at least 10 GB of hard disk space free and at least 3 GB of RAM, it's recommended to download and install the following:

Install VirtualBox: https://www.virtualbox.org/wiki/Downloads

and Vagrant: http://downloads.vagrantup.com/

This allows you to use a virtual machine at the workshop that already has everything set up. Otherwise, you'll need to perform a manual installation. The manual installation guide can be found here: https://wiki.openmrs.org/display/docs/Getting+Started+as+a+Developer, but will be covered in more depth at the workshop.

Getting OpenMRS up and running on your computer

The short version:

• Install git and IRC.
• Manual setup (clone the code from GitHub) OR VM setup (follow VM instructions).
  • VM setup is highly recommended.
• Review the workflow of getting your code merged
• Configure your git remotes. (if manual setup)
• Compile the code.
• Start the web server.
• Go through the web app set up process. (if manual setup)
• You should now have a running local version of OpenMRS on your machine!
• If you want to get a feel for how one would fix a bug in the code, GOTO "OpenMRS bug walkthrough." If you want to fix an actual bug in the code, GOTO "new beginner tasks."

Here are all the relevant links:

• 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

See steps below.

Git setup

See here.

OpenMRS setup

1) 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: Quickest and easiest to do.
• Cons: Harder to debug and less stable if you continue working on OpenMRS (if future releases complicate the setup, it'll be much harder to fix yourself)
• 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".

2) Full Virtual Machine Setup

• This setup uses a virtual machine that has the full OpenMRS setup fully configured for you. You will be using the virtual machine to both write code and to run/test it. Features snapshots of the VM that allow you to very quickly skip to various stages of this demo in case you get stuck. Simply install VirtualBox and copy over the VM's file from a provided flash drive. Then simply run the machine in VirtualBox and begin working.
• Pros: Quick and easy to do. You don't need to install anything on your machine (other than the VM) to work on the project.
• Cons: In order to not need anything else configured on your machine, you'll be using the setup in the VM, which may have a slight learning curve.
• Requirements: 10GB hard disk space and 3GB RAM (preferably 4+GB). Requires you to install VirtualBox and to download/copy over the VM.

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)

It's highly recommended you choose one of the VM based setups. If that's not possible 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 Nicole and Danni about this setup.

Sample Bug Walkthrough

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

Workflow

See here.

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, clone the "official version" from GitHub (happens only once): https://github.com/openmrs/openmrs-core
• Set up your remotes so you get new code and push your original code to the right places
• Pull new changes from upstream (the "official" version of OpenMRS on GitHub, linked above)
• Make local changes on your machine
• Push to origin (your "fork" of OpenMRS on your GitHub account). e.g. here is mine
• 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.

New beginner tasks

Talk to Danni Yu and Nicole Quah (ThoughtWorks).

• Pair programming is great!
• Have Vagrant and VirtualBox installed with at least 10 GB of hard disk space.

If you're working on one of these, please edit the wiki and put 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