During the review of the pull request to the Beman standard resulting from the earlier discussion of the formatting of the license file, there was a discussion about the wording of a new rule that the type of license must be specified in the README.md.
I hope now everything it’s clear and my review was strictly for applying current principles used when writing BEMAN_STANDARD.md and its rules. IMO, beman-tidy should not be relevant here. My current understanding and expectation, is to also check same things if somebody will ask me to manually check if beman.$new_library is Beman Standard compliant (e.g., I expect the exact format for the README file). So same result for manual and automated checking.
I think determining what principle we should use here might become more important as we develop our documentation system further,
If we want to change the principles, that’s other story.
Strict Consistency Benefits:
- Reduced cognitive cost for a developer trying to figure out how to word something.
- Simplified and more accurate tooling.
- Less variability in wording quality.
- Easier to make cross-Beman changes.
Lax Consistency Benefits:- Authors enjoy more freedom of self-expression
- Exceptional cases are better handled. (e.g. in the case where someone wants to call out different parts of the library falling under different licenses)
- More opportunities to innovate on a smaller scale, which can then gain organic adoption elsewhere.
I agree with this comparison, BUT do note that we have some special cases IMO.
We have 3 types of docs in Beman:
- library docs what an author will put inside docs/ in library’s repo - here we just mandate to be in
docs/. NO other rule at all for the moment. - Root README.md inside library’s repo.
2.1. There are some sections where we right now we mandate a content (e.g., SPDX identifier, followed by title, followed by library short description, followed by implements line, followed by status line, and now followed by License section, which only mandates first line).
2.2. Rest of the sections in the README are free-form.
- docs in beman/repo - e.g. BEMAN_STANDARD.md
IMO, 2.1. and 3. must fall into the Strict Consistency category, because we must not allow basic and common data, like implements line, to have divergent format across libraries. Think about how bad would be when then project scales.
A second argument:
- 2.1. does not change to often! Most likely it’s only about bootstrap, and then maybe put a new badge or change library status.
- 3 does not change too often, and not by all people. If people don’t know strict rules for this docs , review will solve the issue.
TLDR: Docs which do not affect lots of library devs OR do not change very often → Strict consistency. Other docs can be in relaxed category, depending on their purpose.