Google Season of Docs/2019/Ideas/PMS Rationale

From Gentoo Wiki
Jump to: navigation, search

PMS Rationale

PMS is the specification behind Gentoo's ebuild and repository format. It is rather good as a specification goes, and we manage to fix issues and update the technical part. What is lacking is a extensive rationale section covering all the decisions made in the past.

A comprehensive rationale guide would help:

  • Ebuild writers who are unsure about some of the parts of the specification. Knowing the rationale behind them would let them understand the spirit of the specification better, and make decisions following that spirit rather than guessing.
  • People submitting new PMS ideas, to match them better with the direction PMS is heading and to avoid unknowingly repeating rejected ideas.
  • Future PMS maintainers to better direct the project, without having to rely on memory of existing project members.
  • Anyone interested in historical research.

The job involves:

  1. Looking for the rationale. We can help some but you will have to look for all the data that is spread across Gentoo, including old mailing list posts, blog posts, and possibly talking to past developers.
  2. Preparing a framework to combine the rationale with the spec. We're open to ideas. This could be inlined in the spec (with some kind of switch to control its output) or separate with appropriate cross-linking.
  3. Integrating as much rationale as you're able to find.


Contacts Required Skills
  • LaTeΧ (and/or some other markup, should you choose to make it separate)