2012-1-30 HTML Form Entry Sprint

General Info

Topic: Html Form Entry Module
Goals: To add a few key new features to the module revolving through program workflows, drug orders, and the new provider model, as well as to work on clearing out the large backlog of reported but unfixed bugs.
Leads: Mark Goodrich (mgoodrich@pih.org)
Date: Jan 30th - Feb 19th 2012

How to Participate

Add your name to the list on this wiki page (with any comments about your availability). If you want to join after the sprint has started just join the IRC channel mentioned above and say hello.

Participants

• Mark Goodrich

• @Darius Jazayeri

• @Daniel Kayiwa

• @raff

• @Wyclif Luyima

• @Mike Seaton

• Judy Wawira

References

The HTML Form Entry wiki pages provide a good overview of the module and its features. All developers should read the Technical Overview before working on the project.

Using Git

The HTML Form Entry module has recently been moved from the OpenMRS svn repo to GitHub, and is serving as a test case for evaluating whether or not to migrate the majority of OpenMRS modules to Git. This sprint should provide a great opportunity for the OpenMRS team to become more familiar with Git and learn Git best practices.

To install Git and check out the HTML Form Entry module, read the IDE Integration section of Migrating to Git wiki page.  If you have any problems configuring Git, don't hesitate to look for help via IRC or the developers list.

To push changes up to GitHub, you will also need to create a GitHub account and then request that the sprint leader add you to the HTML Form Entry team.

Tickets

The tickets below are the open tickets for the current sprint.  Feel free to claim any "Unassigned" ticket marked "Ready For Work".  If you are interested in taking on a ticket that is currently marked as "Needs Assessment" or "Design", please contact the sprint leader directly (mgoodrich@pih.org) or via the development list. 

Before starting to work on a ticket, please make sure to claim the ticket so that no one else ends up working on the same ticket in parallel. Also, if you have to abandon work on a ticket for some reason, please remember to set that ticket back to "Unassigned" so that it will again appear in the pool of available tickets.

JIRA dashboard: https://tickets.openmrs.org/secure/Dashboard.jspa?selectPageId=11253

(Note that this widget does not appear to update in real-time to ticket changes... for the latest results of this query, click here).

Working on a Ticket

Some notes on the recommended workflow one should follow when working on a ticket:

Creating a topic in Git

When you taken on a ticket, it is recommended that you create a new "topic" branch in Git on your local environment to isolate your work on that ticket.  When you make any commits to this branch, please include the ticket number (i.e., HTML-123) in the commit message. This way, once you push your changes up to the main Git repo, JIRA will pick up these commits and they will be listed under the "GitHub" tab on the JIRA page for the appropriate ticket, facilitating code review.

Code formatting

Fortunately or unfortunately, depending how you look at it, the HFE codebase has not been run through the OpenMRS code formatter... so for consistency don't run your code through the formatter or it will be hard for Git to point out the diffs in the code.

Unit testing

All submitted changes (with very few exceptions) should contain unit tests that either test the new functionality being added, or, for bug fix tickets, validate that the bug has indeed been fixed.  Unit tests are especially important for HFE, since the module has much behind-the-scenes functionality and is particularly susceptible to undiscovered bugs that may compromise data quality. If you are unsure of what class you should put your unit tests in, feel free to ask.

On a same note, before submitting changes for review, you should confirm that your changes have not broken any existing unit tests. The module pom has also been configured to test the module against different versions of the OpenMRS core.  For instance, running mvn clean test with the parameter -Popenmrs-1.8 tests the module against the latest 1.8 release.  Before pushing your changes up to Github, you should confirm that all unit tests pass (see exceptions below) against the latest version of all OpenMRS releases.  That is, execute the following commands:

 Important: note that there are known unit test failures when testing against OpenMRS 1.7, so you can skip testing against that release.

 Also note that I have had problems with unit tests failing when run through Eclipse/junit, but passing when run on the command line via mvn.  I run all my tests from the command line... if a test passes from the command line, you can consider it a passing test.

Pushing changes up to GitHub

When you are ready to push your changes up to GitHub, you can perform the following steps to merge your branch into your master branch and then submit your changes to GitHub.  (Note, I'm a Git newbie myself, so if anyone has advice on tweaks to these steps, please let me know)

First, make sure that you have committed all changes to the "topic" branch you created to work on the ticket. (Eclipse: Team->Commit)  Make sure to include the ticket number in the comments for all commits.

Switch back to your local "master" branch (Eclipse: Team->Switch->Master)

Fetch any changes from Github to make sure your local repo is up to date (Eclipse: Team->Fetch From Upstream)

Pull any of these new changes in to the master branch (Eclipse:Team->Pull).

Merge your topic branch into the master branch (Eclipse:Team->Merge) . (You couls also try using the Git rebasing feature here instead).

Resolve any conflicts. When everything is looks good, commit the merged changes to the master branch (Eclipse:Team->Commit)

(Note: if you have made multiple commits to your topic branch, it is possible to "squash" these changes into a single commit when you merge…this is convenient because although you may have made multiple commits to complete a single ticket, these commits could be squashed into a single commit before pushing them up to Github repo.  Bonus points if you figure out how to do this, and extra bonus points if you document it here).

If you pulled in any changes from the GitHub repo, and especially if you had conflicts you needed to resolve, you should rerun the units tests as described above.

When everything is looks good, commit the merged changes to the master branch (Eclipse:Team->Commit)

Now push the changes up to the GitHub repo (Eclipse: Team->Push to Upstream).  Note that will you need to have the appropriate permissions to push to the Github repo.  You can request this privileges by emailing the sprint leader (mgoodrich@pih.org) or making a request on IRC.

Marking the ticket as committed and code reviews

Once you've pushed the changed up to GitHub, go to the ticket and set it has "Committed code".  Once this is done, the sprint leader or another HFE developer will review the ticket and either mark the ticket as resolved or ask for additional changes.  Reviewers will add their comments via the GitHub tab for the ticket in JIRA (unfortunately, we do not yet have the ability to easily create Crucible reviews that incorporate Git changesets as we do with svn).  To add a comment or view existing comments, go to the GitHub tab and then click on the commit uuid for the appropriate commit.

Documenting your changes

Once your changes have been approved, make sure you update the HTML Form Entry wiki if necessary.  Specifically, if you have made any changes to functionality of a tag, make sure your update that tag's entry in the Html Form Entry Module HTML Reference.