Ideas from Jonathan Corbet's talk: The kernel’s limits to growth

[GeorgLink]

The kernel’s limits to growth - Jonathan Corbet from LWN - BUD17-500K1

https://www.youtube.com/watch?v=_hajkHgyVbk (Streamed live on Mar 9, 2017)

Jonathan points out the importance of maintainers, demanding better resources and training.

1. maintainer_documentation
   The project SHOULD document the responsibilities and tasks of the maintainer role.
   Rationale: Much knowledge about maintainership builds up over the years and is not sufficiently passed down to new maintainers. Documenting the maintainer role can help recruit, train, and mentor new maintainers

Jonathan promotes the advantages of group maintainership vs. single-maintainer model. I don't think we should enforce either model, but we might help projects think about it if we asked to document what kind of maintainership model is followed.

2. maintainership_model_documentation
   The project SHOULD document the maintainership model and structure.
   Note: Complements requirement: maintainer_documentation.
   Rationale: A project may have a single-maintainer model or group maintainership. The maintainership may be centralized or distributed across sub-modules. By defining the maintainership model a project gains clarity about its operation and can ensure that underlying assumptions don't go unchallenged.

The proposed badge +1 and +2 include two_person_review.
Jonathan recognizes that the number of reviewers in the kernel does not scale with the number of new contributors and suggests better documentation and training.

3. code_review_documentation
   The project SHOULD document how code review is conducted and how a contributor can learn to review code.
   Rationale: Code review is a cornerstone of quality and secure coding practices. Projects often seek new contributors but lack training and documentation to increase the number of reviewers. An increase in code reviewers lowers maintainer workload while aiding in meeting the badge requirement two_person_review.

[jdossett]

I very much agree with maintainer_documenation. As you state in the rationale, it can really help get new maintainers on board. This can help projects more quickly achieve the bus_factor criterion.

maintainership_model_documentation is similar to what we were going for in governance.

[david-a-wheeler]

Good stuff.

The first two somewhat overlap our current "governance" criterion, and I think it's useful to identify that as a separate criterion. So we kept our "governance" criterion, and merged what was left of the first two into this:

• The project MUST clearly define and publicly document the key roles in the
  project and their responsibilities, including any tasks those roles
  must perform. It MUST be clear who has which role(s), though this
  might not be documented in the same way.
  ^{[roles_responsibilities]}

  Details: The documentation for
  governance and roles and responsibilities
  may be in one place.

  Rationale: Much knowledge about the project roles builds up
  over the years, and is not sufficiently passed down to new people.
  Documenting the roles can help recruit, train, and mentor new
  project members. Projects may choose document the roles
  and responsibilities in one place, and identify who has the roles
  separately, so that the project doesn't need to update the role
  information when people change roles.
  The goal is to make underlying assumptions clear.

We reworded the third one to:

• The project MUST document its code review requirements, including
  how code review is conducted, what must be checked,
  and what is required to be acceptable.
  ^{[code_review_standards]}

  Details: See also
  two_person_review and
  contribution_requirements

  Rationale: Code review is a cornerstone of quality and
  secure coding practices. Projects often seek new contributors but lack
  training and documentation to increase the number of reviewers. An
  increase in code reviewers lowers maintainer workload while aiding
  in meeting the badge requirement two_person_review.
  See
  Ideas from Jonathan Corbet's talk: The kernel’s limits to growth #699
  from GeorgLink.

Thanks!

[GeorgLink]

This is great! Thank you