The time for:
- mentorship
- exemplifying how code review well
- checking test coverage
- design discussions
- enforcing style guides
- ensuring docs make sense
- how to contribute should be in the README of the repo
- anything a contributor needs to know to be able to get tests running,
code built, whatever else they'd need to be able to verify
changes they make before submitting a patch for merging belongs
in the README as well.
- Cross-team / Organizational level people / process stuff: i.e.
*Mozilla's Module Ownership doc
- Style guides
- How to do some generalized thing (write documentation, propose a standard, etc.)
- 10,000 ft view of the whole system (diagrams of how services connect, etc.)
- Narrative style explanations of broad / general ideas (architectural patterns, programming paradigms, patterns, etc.)
- How to contribute
- How to report a bug
- How to request a feature
- How to run tests
- High level overview of build / deployment pipeline
- narrative information about the particular repo
- Where to look for useful / up to date API docs
- Public API usage
- How a particular function works
- Types
- Doctests if possible
- Low-level narrative stuff (i.e. how this class / function fits into other components)
A central place to find, propose, discuss standards. I'm partial to a git
repo hosted somewhere were patch requests with comments are (a la Github).
-
"Arbitrary Choices" (ask me)
- How to affect cultural change? (this shit can't be mandated... or at least when I've seen it tried it failed miserably (and somewhat predictably))...