Difference between revisions of "Project Governance/Module System"

Introduction

Creative Commons software products and technical activities are diverse and larger than what a single person can (or should) directly do by themselves. Moreover, we wish to be as open, inclusive, and transparent as possible, given the nature of our organization and our values. Thus, we seek to organize ourselves in a way that delegates decision-making authority to the edges, while at the same time promoting individuals who prove themselves to be trustworthy and capable. In other words: we self-organize as a meritocracy, insofar as it is possible for us to do so.

Taking the template from the Mozilla governance system (see here), we break up our code and activities 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-focused, but analogous points can be made for non-code.

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 (for example, the Governance module) 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.

These wiki pages are used to document the rules and policies of the system, as well as the current set of 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 our 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:

1. Expertise with the code in or activity of the module
2. Current level of involvement with the module
3. Understanding/vision of where the module ought to be headed
4. Ability to communicate with a diverse, geographically distributed community
5. Willingness to evaluate contributions on their merits, regardless of their source (i.e., no 'not invented here' syndrome)
6. Ability to consider varying perspectives and needs of different consumers of that module

And particularly for code modules:

1. Appropriate understanding of the project's codebase as a whole and the module's relationship to it
2. Ability to evaluate code for that module, including contributions of patches and new features
3. Ability to evaluate impact of code on other parts of the codebase
4. 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 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, but 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.

Creating a New Module

Ideally, a Module should exist for all significant chunks of work or code within our project. However, we prefer to only designate modules for code or activities that are likely to remain permanently (or at least long-term) in our project. Therefore, brand new efforts are usually developed outside the module system, and new modules are created once it is evident and widely agreed-upon that a codebase or activity has met the requirements for module ownership.

If you are confident that a new module is needed, you should post a message to the Module Ownership module.

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.