Request For Comments: A new system for module maintenance

Community
1

I’d like to start a discussion around our model of code ownership and processes of maintenance.

I recently became a /dev/3. The day after it happened, I woke up to a flood of notifications about modules I knew nothing about. This was because I suddenly had “write” permission on every OpenMRS module. I said to myself, “Other large organizations with >100 repos probably don’t have this problem. Why?”

I think the answer is also related to questions like –

  • “Can bring module maintenance to a higher standard?”
  • “Would it be possible for developers to focus more on fewer modules?”
  • “Can we introduce junior developers to more aspects of module maintenance than just fixing tickets?”
  • “How can we foster mentorships between advanced and beginner developers?”

To address all of these questions, I’m proposing that we distribute ownership and maintenance of OpenMRS modules to teams and individuals in the community.

I explain my perspective and proposal in a few slides. Please take a look.

What do you think? If you’re a junior developer, do you know what modules you’d want to help maintain? If you’re part of a contributing organization, how do you imagine this would affect the way your organization contributes? If you’ve been involved with OpenMRS for a while, does this seem like the right direction? If you’ve worked at a mid-size or larger tech company, does this make sense based on how you’ve seen maintenance managed?

@jennifer @burke @c.antwi @dkayiwa @ssmusoke @mseaton @angshuonline

3 Likes
2

If we changed the github configuration setting such that you do not get notifications for repositories that you have not explicitly turned that on, would the problem be solved? :slight_smile:

3

@bistenes this is a bright idea and I second you in having module maintenance as a high priority in the community. When you go through this link https://wiki.openmrs.org/display/docs/Modules you will realize that we have many modules of which some have not been in use for a log time and though some are in use, they are dormant just because they are not often used and by the time they are in use, they are not updated and the document is outdated. To avoid the hustle the few individuals go through when need arise, having every developer stages involved module maintenance will help not only having updated modules and related documents but also provide mentorship to junior developers and hence a strong community.

2 Likes
4

That was just the narrative entry point, the thing that got me started thinking about all this. There are a number of much more important problems I’m trying to solve here:

  • “Can bring module maintenance to a higher standard?”
  • “Would it be possible for developers to focus more on fewer modules?”
  • “Can we introduce junior developers to more aspects of module maintenance than just fixing tickets?”
  • “How can we foster mentorships between advanced and beginner developers?”

There’s no such setting, anyway. Everyone with write access to a repo in GitHub is automatically made a watcher, which encodes the assumption that everyone with write access should be someone who’s contributing to that repo. And when you ask “Why does that assumption work fine for other large organizations?” you encounter the maintenance problem specific to OpenMRS.

Interested to hear your ideas about the problems and the proposal.

5

I’ve talked with @bistenes about is proposal prior to him writing it up, so I’d really like to hear from others first before weighing in too much, but Brandon just wanted to thank you for pulling together such a detailed proposal.

1 Like
6

Thanks @bistenes for putting together such a thoughtful and well written proposal. I definitely encourage others to click into the slides that Brandon put together and give them some thought. Like @mogoodrich, I don’t really want to respond too much until I hear a broader set of opinions. There are a lot of good ideas in what Brandon is proposing, but I expect there are also practical difficulties to making some of it a reality. I’d love to a healthy debate and discussion around this proposal, and thanks again Brandon for kicking this off!

3 Likes
7

@bistenes Thank you for the thought you put into this, and its a great idea in addition I would like to add:

  1. Module Rationalization - do we actually need all the modules, how do we reduce the numbers and which ones can be combined especially as the move is towards REST/FHIR based UIs

    • uicommons, uilibrary, uiframework
    • modules and their UI counterparts
    • moving features to core

  2. The challenge with allocating admins/owners is that interest wanes depending on need, as people move around, for example me on Data Integrity, Patient Flags and Database Backup (2017 to 2018) when the need was there within the UgandaEMR implementation that I support

  3. The practical challenge is that all this needs to be done by a team focused on advancing the core, which team is not currently resourced and available.

  4. Most new developers join during GSoC, but there is no followup from there as life comes into play, but if there was a core team, this would just be accelerating any activities in flight

4 Likes
8

A post was split to a new topic: Attracting more devs to OpenMRS

9

Thanks for the feedback, @sidvaish97. It’s good to hear your perspective. However, most of what you’re talking about is pretty orthogonal to this particular proposal. The problems you bring up are real ones, and the solutions you suggest are good ideas, but it’s not exactly within the domain of what I’m proposing here.

Your suggestion of adding Deprecation Notices to old modules, however, is highly pertinent, and a good idea. Maybe we could even archive some git repos!

I think the problems you’re facing have less to do with module maintenance, which this proposal is addressing, than with onboarding and intro docs. I also had a lot of trouble getting up to speed with OpenMRS. It doesn’t look like intro/onboarding docs made it into the 2020 GSoD projects, but that doesn’t mean you can’t rally people to work on it (and work on it yourself — but yeah, it’s more fun if you can find a teammate). Maybe post in the OpenMRS Documentation Team thread.

2 Likes
10

Hi @bistenes,

Thanks for the initiative. This will not only help the implementers, but also the module developers. I can share some of our experiences In IHS. We always had a default assumption that “if there’s no progress in the past x years, then this module is dead”.

  • First example is Medication Module (unpublished), which we created back in 2018. What we ended up developing is something similar to old Drug management tab which once existed in legacy module. This should have been our developers updating the existing code instead of creating new module. The reason was that our Devs couldn’t find clear answers to whether something similar existed and who to contact to.

  • Facility Data module is next example, in which we contacted the community and described our case. We got a response from one of the core members that we can use this module instead of developing our own. Our team opted for this idea, and we not only bettered this module, but are now in a position to maintain it.

  • Third one is a genuine case of a module which didn’t exist. Common Lab Module was developed and published by IHS after discussing with the community, and concluding that no module existed which could fulfill our requirements. IHS is maintaining this module.

Going through your presentation, there’s hardly anything to disagree with. If we have a page on Wiki explaining in single view which modules are being actively maintained, and who is the maintainer, then this reusing existing code will also improve.

A question here though is about OpenMRS’s maintenance capacity and the number of modules. Can the community maintain all the existing modules? What’s the Modules/Devs ratio? Are there any duplicate modules? We should define certain criteria which declares a module’s end of life. For example, if the last supported platform of certain module was 1.6, then it should either be upgraded or archived. This way, we won’t be overwhelmed with too many modules to maintain.

2 Likes
11

If we have a page on Wiki explaining in single view which modules are being actively maintained, and who is the maintainer, then this reusing existing code will also improve.

Yeah, I think this is an excellent idea. Maybe we could do that with Modules - Documentation - OpenMRS Wiki ?

We should define certain criteria which declares a module’s end of life.

Yes! And also what EOL implies – that the module doesn’t need a maintainer, that the README should get a notice at the top, that the github repo should be archived, that the CI Bamboo job should be archived (is that a thing?), and what to do with the docs? etc. I think it would be great if someone more familiar than myself with how the module ecosystem has changed over the years could propose a definition and procedure for EOLing modules. @mseaton, @dkayiwa, @wyclif ? It might be useful to weave that into this proposal, since it could reduce our maintenance burden, and we can name admins to actually do the work of the EOLing.

1 Like
12

@bistenes First of all, thank you for this well thought-out proposal. As others have said in the thread, there’s very little to find objectionable about it especially in the area of defining module owners and / or people responsible for modules.

I’d just like to put some numbers around this, since that seems to be a key question. Going through the various dev levels, as defined on Talk, we have:

  • 17 /dev/5s (~7 active)
  • 6 /dev/4s (~ 3 active)
  • 37 /dev/3s (~ 10 active)

(The “active” counts here are very subjective; I haven’t backed it with hard data, but these are based on people I’ve seen actively contributing to Talk, Jira, GitHub, Slack, IRC or w/e)

Of that group, I don’t know how many would be willing and / or able to take ownership of one or more modules. Certainly, the count is a little disappointing: ~20 senior devs to ~40 components that make up the RefApp distribution. That’s not to mention the ~210 other repositories that exist in the GitHub organisation (some of which are definitely actively maintained; many of which are probably not).

All that’s to say that we probably need to prioritise which modules we move into the new structure and which we keep in some kind of “community-maintained” mode as a practical matter.

2 Likes
13

@bistenes,

Thank you so much for starting this important discussion.

How we got here

OpenMRS started before git existed. When we started, subversion was da bomb. We were quick to embrace subversion and befriended Karl Fogel, who taught us so much about producing open source software. This included enforcing commit privileges socially instead of technically – i.e., avoid micromanaging write access to code (it’s a versioning system, after all, so it’s easy to undo changes). When we migrated to git about 10 years ago, we brought this ethos with us: be quick to grant write access to code and manage authorization socially. This translated into anyone /dev/3 or above getting write access to our repos. Unless you change the default settings, your git account is configured to auto-watch any repo to which you are granted write access. Since we have 250+ repositories, when you become a /dev/3 you end up, by default, watching a hundreds of repositories.

I appreciate that someone watching hundreds of repositories is effectively watching 0 repositories, since nobody can keep up with activity across hundreds of repositories. As a result, there’s ambiguity on who is truly overseeing repos and a corresponding vacuum of accountability. On the other hand, if you should come across something that needs to get fixed in a community repo, you don’t have to ask permission fix it.

We have 3 to 5 times more repositories than developers. So, there are many repos that are currently loosely maintained or not maintained at all. Switching to an approach where admins of a repo are explicitly defined, will make it very clear which of our repositories – including “core” repositories – are not owned by anyone. I expect it will be the large majority of repositories under OpenMRS org. I’m not suggesting this is a reason not to make the changes you suggest; in fact, making it obvious which repos don’t have an admin or maintainers will help everyone and help devs to see where they are needed.

What happens with repos for modules we use but don’t have an admin or maintainer?

We could define conventions for dealing with repos that have no admin/maintainer. Abandoned & unused repos can be archived or moved to openmrs-archive; however, we need to consider what we do about a repo for a module that is widely used but stable and rarely changed (e.g., calculation).

How do we avoid re-creating the administrative bottleneck and barriers that existed in subversion?

Perhaps in a world of git, easy forking, and PRs it’s less of an issue. But I think there’s more to Karl Fogel’s recommendation of managing authorization socially instead of technically. It’s not just a matter of avoiding administrivia & permission bottlenecks, but also promoting a culture of trust. Perhaps we could make a lightweight bot that would allow anyone who is a /dev/3, /dev/4, or /dev/5 to grant admin access to themselves to any OpenMRS repo. If an admin leaves the community and abandons a repo, you don’t have to submit a ticket or hunt down an org admin, you just grant yourself admin access to the repo or, if you aren’t a /dev/3 yet, ask any seasoned devs you happen to be working with to help you out.

When does a repo need to live under OpenMRS org?

It might help to move away from an “everything needs to be under OpenMRS org in GitHub” model. While it can be convenient to search repos under the OpenMRS org, it’s just as easy to search GitHub for openmrs. Or we could promote use of the openmrs topic a search GitHub for topic:openmrs. Getting comfortable with having only a handful of repositories hosted under the OpenMRS org in GitHub and having “official” OpenMRS repos hosted under various individuals’ or other organization’s account could help promote the type of module maintenance you describe. For example, does it really matter that the openmrs initializer module is hosted by mekomsolutions? Maybe it’s even better than hosting it under the OpenMRS org. But we need a shared understanding of when & why a repo belong under OpenMRS org.

3 Likes
14

@mogoodrich, are you going to let me have the last word? :stuck_out_tongue:

1 Like