Add a governance.md file to all your OSS projects

Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone

When developing software systems, we have to face a long-life process where we cope with a huge number of development tasks (e.g., implementing new features or fixing bugs). To success, it becomes crucial to effectively and precisely prioritize these tasks. For that, a project should define (and enforce) what is normally referred as governance rules, or in plain English, a set of policies telling us how the project community will decide which tasks are accepted/rejected, how they are going to be sorted, etc.

The problem is that usually all this key information regarding the project governance is not explicited anywhere (or in the best case, scattered in many places). Therefore we propose to have a governance.md file in the root folder of every open source project that clearly defines how the project is governed.

In the last years, it has become quite common to include a file called contributing.md in OSS projects. This file usually instructs developers about how they can contribute to the project (e.g., how to send a pull request, how to create and issue, etc.). However, it usually does not say how such contributions are going to be treated (e.g., how long it will take to evaluate a pull request or who is going to decide its acceptance). We propose to contribute this file with a new file called governance.md, where project managers can specify the rules governing the decision making process in the project. 

In the last months, we have studied the existing difficulties to identify the rules governing OSS and proposed a DSL to facilitate their explicit definition (plus a form-based wizard to ease the creation of DSL-based governance rules) in the governance.md file. Additionally, we have also provided a decision engine implemented in Mylyn to automatically enforce such governance rules (the engine updates the status of project tasks, issue/bug trackets are accessed using Mylyn). Full details of our proposal can be read here. They will also be presented in the track on Software Engineering in Society part of the International Conference in Software Engineering (ICSE-SEIS).

As an example of the governance DSL, our project called Collaboro includes this rule:

Project Collaboro { 
   Roles: Leader
   Deadlines: 
      D1 : 7 days
   Rules: 
      R1 : LeaderDriven { 
         applied to All
         when TaskReview, PatchReview, Release
         default None 
         deadline D1 
         } 
      }

The DSL definition includes a set of roles, deadlines and governance rules. In this example, being a project with only a couple of developers, the governance of the project is quite simple: everything will be decided by the project leader in a short period of time (i.e., one week). Thus we use a LeaderDriven governance strategy which is applied to all the development phases (i.e., TaskReview, PatchReview and Release). Note that the community of users of the project have no saying in the future evolution of the project (beyond suggesting things, they have no voting power to drive the project evolution).

The previous rule can be verbalized and included in the governance.md file of the project. In this example we have generated the English version of the rule but a permalink is also provided to show the same rule in other languages (the DSL itself, in natural language and others that could be added in the future).

These are the main rules we follow to accept contributions:

All proposals for bugs and feature requests will be accepted or rejected in 7 days by the leader of the project unanimously 
http://atlanmod.github.io/governance/#/generate/2010000000500000070000

All patches for bugs and feature requests will be accepted or rejected in 7 days by the leader of the project unanimously 
http://atlanmod.github.io/governance/#/generate/2110000000500000070000

All bugs and feature requests will be accepted or rejected for the next release in 7 days by the leader of the project unanimously 
http://atlanmod.github.io/governance/#/generate/2210000000500000070000

In more complex projects, governance rules can be much more complicated. For instance, if we had to model the governance rules to accept/review development tasks in a project like Apache Web Server, a (partial) DSL definition would look like the following:

Project Apache {
   Roles : Developer, Committer, PMCMember, PMCChair
   Deadlines :
      twoDays : 2 days
   Rules :
      codeRule : Ratio {
         applied to Task (tag = code)
         when TaskReview
         people Developer, Committer, PMCMember, PMCChair
         range Present
         minVotes 3
         ratio 1
         deadline twoDays
      },
      noCodeRule : Majority {
         applied to Task (tag != code)
         when TaskReview
         people Developer, Committer, PMCMember, PMCChair
         range Present
         minVotes 3
         deadline twoDays
      }
}

The former rule is a ratio majority rule (i.e., tasks must receive a support over a specific percentage to be selected) which is applied to those tasks including the tag code (i.e., tasks involving changes in the code). All people belonging to the roles linked to the rule (see tag people) and presently available (see tag range) can vote. It is required a ratio of agreement of 100% (i.e., meaning that everybody has to agree) and at least three votes. Finally, the rule defines a deadline of two days, although the precise length is not specified in the project documentation. On the other hand, noCodeRule is a majority rule (i.e., tasks must receive a support over 50% to be selected) which is applied to those tasks not including the tag code. Like the previous rule, it is required at least three votes to make a positive decision and the deadline is two days after the creation of the task.

This call for a governance.md file is still in its early stages so we could really benefit from your ideas and suggestions. Therefore, we kindly invite you to read and comment on our proposal, play with the generator, the DSL, and tell us what you think. You can find the generator here and the DSL is described here.

If you are a frequent reader of the blog, you may remember other posts where we reported on our advances in this topic. For instance, we studied the reasons for not contributing to OSS projects (the call and the results), our tentative idea on governance and eventually our governance rule generator (together with a survey).

Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone

Reply

Your email address will not be published. Required fields are marked *