The Manila spec repo was created for the Newton release and did not get used very effectively. Many specs did not get reviews, even fewer specs were merged during the release, and some features with merged specs did not get code review priority.
In order to ensure that specs do get reviews, and also to help focus the efforts of the reviewers, I propose adding some official deadlines and rules for handling of specs.
We have a few specific problems, some new in Newton, and some which have grown worse over time:
The purpose of the proposed change is to focus the core reviewer team on a smaller set of features, and to give contributors earlier feedback on their proposals. Rather than having a lot of things with small chances of success, we would like to have a few things with large chances of success.
First, I propose defining what it means to merge a spec. Merging a spec during a release will mean:
Note that merging a spec will not guarantee that the code for a feature will merge only that we will try. More importantly, NOT merging a spec will mean that we don’t intend to work on that feature, and it will be reconsidered for the following release.
Next, I propose a specs deadline:
Because merging a spec will imply that the team will spend sufficient time reviewing that feature, the team will need to limit the number of merged specs, even if specs meet all of the other requirements to be merged. The team will need to prioritize the proposed features and merge the higher priority ones first, and stop merging specs when there’s no more available review bandwidth.
Because the number of proposed specs can be more than the whole team can reasonably review in the time before the first milestone, the team should designate a subset of the specs as “review focus” specs which everyone is expected to review, while the remaining specs will be reviewed on a volunteer basis. Review focus specs will be listed on an etherpad agreed to by the core reviewer team.
Lastly, I propose that we require specs for any kind of change with broad impacts. It’s better to agree on the design before we get too deep into implementation.
New drivers and changes to drivers should not ever require specs, and thus driver changes are not affected by these deadlines. The exception would be a change to a driver that implemented something unusual or controversial and thus required community discussion.
This specs process requires several decisions to be made:
It’s important for the contributors involved with Manila to have influence over the direction for the project, so I propose that none of these decisions be made solely by the PTL, and that decisions should be made as democratically as practical (with PTL resolving deadlocks).
The whole community should provide input on the decision for which specs to focus on for reviews, and also the prioritization of specs. We want to work on things which the largest number of people will find valuable so we will gather input during weekly meetings and using etherpads about what we should focus on.
Determination of the cut line has to be made by the core reviewer team because the commitment to review new featutes comes from the core reviewers and the goal of this change is to avoid overcommitting.
Merging of individual specs should be done as usual with two +2s from core reviewers from different companies if the spec is low priority, and with +2 from a majority of the core reviewers for high priority specs.
Designation of a spec as “high priority” which changes the merge deadline from milestone-1 to milestone-2 should be done by agreement by the core reviewer team, because of the additional review commitment and increased risk such a decision carries.
The purpose of giving “high priority” specs more time than “low priority” specs is not to divert attention away from the high priority stuff, but to make the decision to push stuff out of the release as early as possible. This process can’t make people review specs earlier if they’re not inclined to, but we can reduce the set of specs that need reviewing by drawing a cut line fairly early, and hopefully that will focus our limited review time more productively.