Module Ownership System
Clone this wiki locally
The WebThings module ownership governance system is inspired by (shamelessly copied from) the Mozilla module ownership system.
Modules and Module Owners
The WebThings project is too big for any one person to make the decisions. Instead, decision-making is distributed to a range of participants through the project being split into “Modules”, each of which has a Module Owner. A module is, in the case of code, a piece of functionality, or in the case of non-code, an activity, with reasonably well-defined boundaries. (Some of the below explanation is code-focussed, but analogous points can be made for non-code.)
Of course, “reasonably well-defined boundaries” doesn’t provide absolute clarity. Trying to create absolute definitions would require elaborate rules and exceptions that aren’t needed in most cases. Rather than spend energy devising such definitions, we prefer to let module owners manage any overlap or shared ownership if possible, with mediation when necessary.
The work of the module owners and the health of the system are overseen by the owner and peers of the “Module Ownership” module. A number of larger modules (e.g. WebThings Gateway) have sub-modules subordinate to them. The module owner and peers of the appropriate module is responsible for sub-module ownership appointment and removal in those areas. The WebThings project uses its wiki to track modules, module owners and peers.
The Module Owner Role
A “module owner” is the person to whom leadership of a module’s work has been delegated. The responsibilities of module ownership might include, in the case of a code module: improving code quality, implementing revisions and innovations as appropriate, coordinating development with that of the rest of the codebase, developing and maintaining a shared understanding of where the module is headed, developing APIs where appropriate, documenting as much as possible, responding appropriately to code contributions, design suggestions and stated needs of the community, and creating an environment where competent newcomers are welcomed and included.
A module owner’s OK is required to check code into that module. In exchange, we expect the module owner to care about what goes in, respond to patches submitted by others, and be able to appreciate code developed by other people. Module owners have a fair amount of flexibility in how they do this. We do not have an elaborate set of rules or procedures for how module owners manage their modules. If it works and the community is generally happy, great. If it doesn’t, let’s fix it and learn.
Module Owners need not do all the work of managing the module themselves. Module owners may identify others who can also approve code for check-in into a module. These developers are known as “peers” and ought to possess many of the qualities of a good module owner. Module owners must designate to a peer the evaluation of their own code; module owners are not permitted to review their own code. If there is no module owner, the OK of a peer is sufficient to check code into that module.
Module owners are not tyrants. They are chartered to make decisions with input from the community and in the best interests of the community. Module owners are not required to make code changes or additions solely because the community wants them to do so. (Like anyone else, the module owners may write code because they want to, because their employers want them to, because the community wants them to, or for some other reason.) Module owners do need to pay attention to patches submitted to that module. However “pay attention” does not mean agreeing to every patch. Some patches may not make sense for the WebThings project; some may be poorly implemented. Module owners have the authority to decline a patch; this is a necessary part of the role. We ask the module owners to describe in the relevant bug their reasons for wanting changes to a patch, for declining it altogether, or for postponing review for some period. We don’t ask or expect them to rewrite patches to make them acceptable. Similarly, module owners may need to delay review of a promising patch due to an upcoming deadline. For example, a patch may be of interest, but not for the next milestone. In such a case it may make sense for the module owner to postpone review of a patch until after matters needed for a milestone have been finalized. Again, we expect this to be described in the relevant bug. And of course, it shouldn’t go on very often or for very long or escalation and review is likely.
Escalation and Review
The owner and peers of the Module Ownership module will get involved if controversy develops and cannot be resolved otherwise. A module owner may ask for a public statement of agreement with a particular action. Sometimes other contributors suggest ways in which a module owner might improve. Sometimes there is ongoing controversy. We prefer that the community resolve these issues when possible, but acknowledge that this can’t happen all the time. We try to avoid making absolute decisions like “this must happen” but will do so if required.
Criteria for Module Ownership
There are a number of important elements of good module ownership. First is the person’s expertise with the area in question. But over time we’ve learned that a set of additional criteria is also important, and that a great hacker can be a poor module owner. The criteria that go into the mix for a good module owner include:
- Expertise with the code in or activity of the module
- Current level of involvement with the module
- Understanding/vision of where the module ought to be headed
- Ability to communicate with a diverse, geographically distributed community
- Willingness to evaluate contributions on their merits, regardless of their source (i.e., no ‘not invented here’ syndrome)
- Ability to consider varying perspectives and needs of different consumers of that module
And particularly for code modules:
- Appropriate understanding of the WebThings codebase as a whole and the module’s relationship to it
- Ability to evaluate code for that module, including contributions of patches and new features
- Ability to evaluate impact of code on other parts of the codebase
- Ability to resolve different needs through factoring or other abstraction techniques when appropriate
Designating a Module Owner
Appointment, removal and change of sub-module owners and peers is normally the work of the owner and peers of the module covering that area of the project. The Module Ownership Module team will generally intervene only in cases of dispute.
We prefer that an individual work with a module for some time and demonstrate the ability to fulfill most of the criteria most of the time (we’re not naive enough to require perfection), and that a consensus form about designating this person as the module owner. This way the designation is more of a confirmation than an appointment. We haven’t always done this, and we haven’t always done it well.
This means that there will be times when there is no module owner. In particular, in some cases modules have received little attention, have started to rot, and some brave soul steps up to figure things out and get us back on track. We’ll shower these folks with thanks for tackling the job, however we may not immediately designate them as module owners. Almost by definition, it will be difficult for this person to have demonstrated some of the criteria, until some time is spent working with the module. It’s possible that someone’s expertise is broad and so deep enough to do this, but we would expect this to be the exception rather than the rule.
In determining a module owner, the criteria above are not necessarily accorded the same weight for each module. The importance of a particular element depends on the module. For example, code criteria 1 (appropriate understanding of the WebThings codebase as a whole and the module’s relationship to it) and 3 (ability to evaluate impact of code on other parts of the codebase) will be of less importance for modules that are self-contained, and of great importance for modules containing core technologies which affect other parts of the code significantly. Similarly, general criterion 6 (ability to consider varying perspectives and needs of different consumers of that module) and code criterion 4 (ability to resolve different needs through factoring or other abstraction techniques when appropriate) will be less important to a module which serves a specific, clearly defined function for a small number of contributors, and critical to a module which supports a variety of uses and a broad contributor group.
Relationship to GitHub Issue Tags
Occasionally there is some confusion between the role of code module owner/peer and that of default owner of a GitHub Issue tag. The roles are quite different. A tag owner is the person best suited to receive incoming bug reports for a particular tag, not necessarily the person best suited to make decisions about the direction of the module and the review of its code. There are several reasons for this. First, GitHub Issue tags do not map exactly to modules. That’s because tags reflect the way bugs are perceived and experienced, not necessarily the structure of the code. Second, managing bugs is a different task than managing the code of a module, and the skills required are different. Some great hackers are not so good at reviewing bug reports regularly, tracking progress, reassigning bugs to correct owners, making sure test cases exist, etc. Some contributors are excellent at these skills but not necessarily at directing code development. So in some cases the GitHub Issue tag owner and the module owner may be the same person, but in many cases they will be different.
Poorly Maintained Modules
Periodically a module is not well maintained and no longer interacts well with the rest of the codebase. This can happen where there is no module owner, or when a designated module owner is too busy with other things to tend to the module. Conceivably it could happen when a module owner is active, but has an approach to a module that the community in general believes is inappropriate. We prefer that the development community identify such modules, propose a solution, and implement improvement. If this can’t happen for some reason then the Module Ownership Peers will get involved to find the best possible resolution.
Emeritus Owners and Peers
An Emeritus Owner is a former module owner who has handed over ownership to someone new. The ability to develop new leaders is important to health of the WebThings project and our mission. It’s also very important to recognize when someone else is the best leader of an area or activity, and then to transfer authority smoothly. This is how we remain robust and relevant as an organization that outlives any one of us. There is a matching status of Emeritus Peer for those who used to be but are no longer peers of a module.
The status of Emeritus Module Owner is a factual status. It is not a qualitative decision about the value of a person’s service as a Module Owner, or about the effectiveness of how ownership of the Module was passed on. Emeritus Module Owners will have varied in their skill in ownership, and in developing and executing a succession plan. When those sort of qualitative understandings are needed then other owners, peers and contributors to the Module should be consulted.