2017-06-22 OpenLMIS Contribution Process Review


Performance-Related Tickets

Malawi's tickets weren't always clear because were were rapidly making decisions. The tickets thus drifted - a delta developed between what they said and how the team understood they had to be implemented. They were thus confusing to outsiders, which is a problem we're trying to avoid in the future.

Rejection-Status Pull Request

The "REJECTED" status ticketed was also a pain point. We were told that the work could be done and would be accepted into core. This wasn't the case though: it took two weeks from the time the PR was made until the time Core approved the business related changes it introduced. This caused a problem when the code eventually was merged because its dependencies had changed.  We were lucky it was simple to address this problem.

The core team learned from the "REJECTED" status ticket that we should perhaps do things more formally. Once the pull-request was made, we realized that we couldn't fully communicate all its changes to stakeholders. We could have better communicated initially that we needed more business analysis and buy-in from stakeholders. Needed to be communicated to product committee.

Need to document what the impact is / what UI or functionality changes will be for end-users. 


  • What level of detail belongs in the ticket, versus belongs elsewhere? Are the tickets doing double duty—written for developers but also informing the core team / business users about the design and ramifications of the ticket.
    • Josh: other open source projects do have that level of detail and documentation within the tickets (impacts for users, UI, technical architecture).
    • Some of those details in the ticket were important for developers to have clear (like rights checks).
    • It would be nice if there was pull request documentation that matched our functional documentation — but time constraints for a project makes this difficult
      • There used to be a "project proposals" section of the wiki that was verbose and under used

Missed opportunity for making a configurable status for Requisitions. How could we have used this opportunity to tackle a bigger improvement like that? Open Source projects sometimes find a way to take opportunities like this when they come up.

Next Steps:

  • Update documentation for pull requests to be pulled in. Questions might be:
    • Does it need to be shared with and reviewed by the product committee?
    • Does it change the UI in a meaningful way?
    • The documentation should help us to set expectations around timing. The timing we've adopted for Malawi won't likely be typical.

Code Review Process

Q: Some large pull-requests are being approved/merged very quickly. Are they being given enough attention prior to the merge?

A: Because we're using github for reviews, you can see who approved the PR. Our workflow is reasonable, and we sometimes have several reviewers. The fact that some PRs were merged quickly doesn't mean they were accepted cavalierly. Perhaps the core team should consider doing more QA on code contributed from outsiders, though, than on code developed within its own team. 

  • Perhaps incoming work should be put on the Core's JIRA project, and explicitly reviewed during sprint showcases. Otherwise, these additions are largely invisible to team.
  • Another idea is to merge the Core and Malawi JIRA projects into one. The teams could still work independently and on different sprint cycles. This would improve work visibility as well as velocity-tracking. 
  • CI/Jenkins Issue: The Pull Requests are not tested by Jenkins, so developers have no immediate feedback of any failures or issues. (Compare that to core team process of contributing draft work immediately to master, where Jenkins gives immediate feedback if any test failures or issues.)
  • Suggested Documentation: Monthly/periodic releases. PRs get reviewed as a priority; large ones may take longer. Once PRs are approved and merged in, they are available in SNAPSHOT versions of services right away, and will be in the next official monthly official release. It's best to have on-going dialogue between the two teams so there is awareness of the upcoming release dates. Implementations should not build an expectation that releases will happen quickly or immediately.

Malawi's Git Repositories

Has it been problematic for MW to use/share core's OpenLMIS github organization? It requires copying-and-pasting code from one repo to another, and that may lose intervening changes. And it loses the commit history.

Another issue is that one pull request can depend on another, causing problems. 

The MW team developers know this issue from the beginning, so on some repos they can just work in core repo. But it would be easier to have repositories in a separate organization.

Next Steps

  • move the Github repos for Malawi and future implementation projects into their own GitHub organization; it should be easier without credentials issues.