|
Here is a [https://photos-5.dropbox.com/t/1/AAAAYoZcyOdcpW-q2FdsrAjD6waykEdpsOAzY8zpJGRlPQ/12/110243113/png/1024x768/3/1416646800/0/2/Capture%20d%27%C3%A9cran%202014-11-21%2015.34.34.png/8UfRRfbN2rbiRiztoMIyZ7wCf_uKZbgKEZjfTov0TBE screenshot]! (please ignore the French)
= Relevant Links =
= What to install before the workshop =
Here are all the relevant links for future use:
* [http://en.flossmanuals.net/_booki/openmrs-developers-guide/openmrs-developers-guide.pdf Developer's Guide]
* [https://drive.google.com/folderview?id=0B47JK2xjSdD0WC1KUWlPSUU2MXM&usp=sharing Google Drive with VMs] Just download OpenMRS.tar.gz
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:
* [https://docs.google.com/presentation/d/1Wa3TqRJSJgXLOt_rehlGa6NK6uh_2oW8Y04xjagywPY/edit?usp=sharing Wintersession Presentation]
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:
* [http://opensourceprinceton.wikidot.com/ OSAP wiki] (which has even MORE links!)
* [http://opensourceprinceton.wikidot.com/openmrs-getting-started Background OpenMRS reading] (more links to check out in your free time)
* [https://github.com/hypotext/OpenMRS-dev-setup/wiki/Setting-up-git,-plus-workflow-tutorial Git + workflow tutorial]
* [https://github.com/hypotext/OpenMRS-dev-setup/wiki/Running-the-OpenMRS-webapp-and-viewing-changes-in-code Running the webapp and viewing changes in code]
See steps below.
= Git setup =
See [https://github.com/hypotext/OpenMRS-dev-setup/wiki/Setting-up-git,-plus-workflow-tutorial 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) Partial Virtual Machine 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 [https://www.virtualbox.org/wiki/Downloads VirtualBox]. Download the [https://drive.google.com/file/d/0B47JK2xjSdD0ckZPdnUwaFJXOG8/view?usp=sharing 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.
* Pros: Quickest and easiest to do.
* Cons: Less intuitive of what's going on unless you are very comfortable with working from the command line.
* 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.
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
before issuing "vagrant up".
2) Full Virtual Machine Setup
'''3) Manual 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 =
= Workflow =
Before working on a current bug, you might like to try completing [https://openhatch.org/wiki/OpenMRS_sample_bug the walkthrough of this older one] in order to get a feel for the workflow.
= General Workflow =
See [https://github.com/hypotext/OpenMRS-dev-setup/wiki/Setting-up-git,-plus-workflow-tutorial 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, clonefork 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 upstreamthe (the "officialupstream" version of OpenMRS on GitHub, linked above)remote
* Make a new branch for the ticket you'd like to work on
* Make local changes on your machine
* Make local changes on your machine to fix the bug/implement the feature
* Push to origin (your "fork" of OpenMRS on your GitHub account). e.g. here is [https://github.com/hypotext/openmrs-core- mine]
* Push to your "origin" remote
* When done, make a pull request on upstream, which will be reviewed. [https://github.com/openmrs/openmrs-core/pulls Current OpenMRS pull requests]
* Repeat
* Hopefully get your pull request merged into upstream! [https://github.com/openmrs/openmrs-core/pull/1160 Looks like this].
[https://github.com/hypotext/OpenMRS-dev-setup/wiki/Setting-up-git,-plus-workflow-tutorial See here for a more detailed walkthrough].
= OpenMRS bug walkthrough =
= New Beginner Tickets =
Talk to Chris Hay and Katherine Ye.
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).
Check out code from here: https://github.com/hypotext/openmrs-core
We'll be walking you through fixing [https://issues.openmrs.org/browse/TRUNK-3780 this bug], testing changes in the webapp, writing tests, and submitting a pull request!
== Your First OpenMRS Ticket ==
In this workshop, you will work through the full development process involved in contributing to OpenMRS. To contribute to the project, one first needs to pick a sub-project to work on. In the open source community, this means claiming a ticket to work on. A ticket provides an overview of an issue that needs to be fixed or a new feature to be added, and is how work is divided up among contributors. In this workshop, you will pick a ticket to work on and hopefully fix the issue or create the new feature. Below is a list of starter tickets that will allow you to make a real contribution to the project. If you'd like to ease your way into this process, we also have a sample ticket that you can work on. The sample ticket is a real ticket, but is one that has already been completed. This allows you to work through a ticket similar to the starter tickets provided, but with a guide and provided solution there to assist you when needed.
You can choose from a list of starter tickets here:
If you're working on one of these, please edit the wiki and put your name next to it! Also, talk to Danni Yu and Nicole Quah (ThoughtWorks).
* [https://issues.openmrs.org/browse/TRUNK-3895 TRUNK-3895] Filter daemon user from user-related API methods
* [https://issues.openmrs.org/browse/TRUNK-3479 TRUNK-3479] Concept Validator should ignore short names
* [https://issues.openmrs.org/browse/TRUNK-3274 TRUNK-3274] Voided person addresses and names should be ignored by the short patient form validator
* [https://issues.openmrs.org/browse/TRUNK-2660 TRUNK-2660] Validate field lengths of domain objects in management pages
* [https://issues.openmrs.org/browse/TRUNK-4539 TRUNK-4539] Support validation in the UI for the database characters set for a field or column
* [https://issues.openmrs.org/browse/TRUNK-3849 TRUNK-3849] Move Address and Name layout support classes from web layer to api layer
* [https://issues.openmrs.org/browse/TRUNK-2941 TRUNK-2941] Find+Move mediawiki archive pages in confluence
* [https://issues.openmrs.org/browse/TRUNK-3709209 TRUNK-3709209] SecretMRNgen answerDuplicate shouldGlobal be encryptedProperties 1
* [https://issues.openmrs.org/browse/TRUNK-3638 TRUNK-3638] Separate liquibase file into separate files per version
* [https://issues.openmrs.org/browse/TRUNK-3657 TRUNK-3657] Delete clob data storage when deleting a form resource
* [https://issues.openmrs.org/browse/TRUNK-4575 TRUNK-4575] TestData - Duration Unit not usable
* [https://issues.openmrs.org/browse/TRUNK-3746 TRUNK-3746] Error adding a ConvSet in a second form schema
* [https://issues.openmrs.org/browse/TRUNK-4473?filter=10068 TRUNK-4473] Form Resource (Long-Text) causes error with binary file upload
List of all intro tickets:
Or, you can choose to work on the sample ticket here: https://issues.openmrs.org/browse/TRUNK-3780 Talk to Chris and Katherine about this. The sections below will cover the process of fixing the prefix bug.
* https://tickets.openmrs.org/secure/IssueNavigator.jspa?mode=hide&requestId=10068
== Analyzing a Ticket ==
After clicking on one of the links above, you'll come to a page that lists the details for an issue/feature that needs work. Ideally, it'll provide descriptions of the current behavior, the desired behavior, and areas of interest that might help fix the issue. Make sure to read through the comments section to get feel for the progress that's already been made.
For the sample ticket, please initially only read below the line saying "###DEPRECATED (this was the previous description)". This is what was originally provided when the ticket was created and was all that was given to work off of. Everything above the line was added by Chris and Katherine while they were in the process of fixing the issue, so only read this after analyzing the ticket yourself.
The issues at hand: patient search doesn't do prefix search for 2 character searches but does work for 3+ character searches. So it seems that somewhere it must be manually defined to only do prefix search with 3+ characters. How could this be used to create the desired behavior and fix the bug?
== Replicate the Issue ==
After familiarizing yourself with the ticket, you then need to replicate the error. This will help provide additional context/error logs about the issue and will also ensure that you will be able to test whatever changes you make. To do this, you'll likely need to start the webapp. Help in doing that can be found [https://github.com/hypotext/OpenMRS-dev-setup/wiki/Running-the-OpenMRS-webapp-and-viewing-changes-in-code here].
Sample ticket: Start the server and go to the webapp. Login using admin/Admin123 (try admin/test if that doesn't work). Navigate to the patient search and try searching for the names described in the ticket. Can you reproduce the bug? You may need to make some test data in the webapp.
== Looking Through the Code Base ==
Once you can replicate the error, try to find and open the files related to the areas of interest (if provided). One way you can do this is by opening up the OpenMRS project's folder in Sublime and clicking on Find->Find in Files. Then simply search for whatever might seem relevant to the issue.
If you prefer to work from the command line (using emacs, vim, nano, for example), navigate to openmrs-core. Then you can search for code with "grep -r "STRING HERE ." (don't forget the period at the end -- it tells grep to look in the current directory.
Sample ticket: Search for PatientSearchCriteria, PatientServiceImpl, HibernatePatientDAO, and DWRPatientService. Ctrl-f or grep through these to try to find something that might specify a minimum length string as a search requirement. Afterwards, look for similar variables via the Find in Files method. In our case, for TRUNK-3780, the same change was needed to be done in 2 files (since the java backend and javascript front end are separate).
== Testing Your Changes ==
After making your changes, test them by trying to replicate the original issue once more. You can do that by following the instructions to get the webapp up and running (making sure to RE-COMPILE and DELETE OLD DATA), then testing searching for users' names. You can also run tests you've added to the code by doing `mvn clean install` in the top-level openmrs-core directory. Check the output to see which tests fail and pass.
If your compilation fails because of failed tests, check to see if those tests are still necessary. If the desired behavior ''should'' cause them to fail, comment them out temporarily or make them work for the new code and try to compile again. If you now get the desired behavior, then you're almost done! Now you just need to add more unit tests.
This is important because if you submit a pull request to a project, the maintainer will almost certainly ask you to write tests.
Sample Project: Follow the above and if you get stuck and would like additional help finding the changes that need to be made, take a look at the commit summary for the accepted solution: https://github.com/openmrs/openmrs-core/pull/865/files
== Making Unit Tests ==
Once you've fixed the bug or added the new feature, you want to make sure that others don't break it. To do this, find existing tests in the code base that relate to your ticket. (We won't tell you exactly where to find them, but if you're stuck, you can refer to the TRUNK-3780 merged pull request.)
Modify existing tests so that they properly test for the new behavior. Then add any additional tests you find necessary to ensure that your changes are kept when future contributors start messing with the code. Once this is done, re-compile and re-test your changes to make sure everything works.
You can run tests by doing `mvn clean install` in the top-level openmrs-core directory. Check the output to see which tests fail and pass.
== Submitting the Pull Request ==
Ask Chris or Katherine to help you submit your changes.
Submit your pull request here: https://github.com/hypotext/openmrs-core
= 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!
* [https://issues.openmrs.org/browse/TRUNK-3895 TRUNK-3895] Filter daemon user from user-related API methods
* [https://issues.openmrs.org/browse/TRUNK-3479 TRUNK-3479] Concept Validator should ignore short names
* [https://issues.openmrs.org/browse/TRUNK-3274 TRUNK-3274] Voided person addresses and names should be ignored by the short patient form validator
* [https://issues.openmrs.org/browse/TRUNK-2660 TRUNK-2660] Validate field lengths of domain objects in management pages
* [https://issues.openmrs.org/browse/TRUNK-4539 TRUNK-4539] Support validation in the UI for the database characters set for a field or column
* [https://issues.openmrs.org/browse/TRUNK-3849 TRUNK-3849] Move Address and Name layout support classes from web layer to api layer
* [https://issues.openmrs.org/browse/TRUNK-2941 TRUNK-2941] Find+Move mediawiki archive pages in confluence
* [https://issues.openmrs.org/browse/TRUNK-3709 TRUNK-3709] Secret answer should be encrypted
|