PEP 1, 12 and template: update style - #5082
Conversation
Documentation build overview
9 files changed ·
|
warsaw
left a comment
warsaw
left a comment
There was a problem hiding this comment.
I'm -1 on changing the PEP 12 template away from all-caps headers, for the reasons given below. -0 for changing PEP 1 headers. The other improvements (e.g. not using .e.g. 😄 ) and fixing the case for reStructuredText seem fine though!
|
|
||
|
|
||
| Backwards Compatibility | ||
| Backwards compatibility |
There was a problem hiding this comment.
I don't think we should change the template. There's nothing wrong with the existing all-caps headers except that it doesn't conform to our current standard. Consistency is useful, but what does PEP 8 say about consistency? 😄
Since we already have so many PEPs that are using this template, changing it does introduce a larger inconsistency! All those PEPs using the all-caps headers will be inconsistent and I don't think we should go back and change them.
Yes, we have to accept drift when we add a new section (such as Change History) or re-order them (like Rationale moved to after Specification), but there were some substantive reasons behind those changes.
|
|
||
|
|
||
| PEP Audience | ||
| PEP audience |
There was a problem hiding this comment.
Changing PEP 1's headers is fine in isolation since it's not a template, but ... is it worth it? We have so many all-caps headers in the PEPs, I'm not so sure.
2 participants
We usually don't review PEPs to the same level as the main docs following our style guide, as each PEP is more of a standalone document compared to the docs' editorial whole; and also not to delay publishing and discussing PEPs: authoring and shepherding a PEP is a big task as it is.
However, let's update PEP 1, 12 and especially the template to set an example.