Update, copyedit and format Readme and Contributing Guide #2352
Conversation
| start reading at PEP 1 (`pep-0001.txt <./pep-0001.txt>`_ in this repo). Note that | ||
| PEP 0, the index PEP, is now automatically generated, and not committed to the repo. | ||
| To learn more about the purpose of PEPs and how to go about writing one, please | ||
| start reading at `PEP 1 <https://www.python.org/dev/peps/pep-0001/>`_. |
There was a problem hiding this comment.
Does the github renderer support :pep`1`?
There was a problem hiding this comment.
I thought it didn't when I tested it a few looks ago, which is why I didn't use it here, but it looks like that's only for linking subsections and/or custom link text. So, we could use it in this specific case, but a standard link would still need to be used for the specific-section reference below, and it also won't be too helpful for anyone viewing the Readme or Contributing Guide locally. So, IMO, I suggest just consistently using standard links in the readme and contributing guide here.
| start reading at `PEP 1 <https://www.python.org/dev/peps/pep-0001/>`_. | ||
| Also, make sure to check the `README <./README.rst>`_ for information | ||
| on how to render the PEPs in this repository. | ||
| Thanks again for your contributions, and we look forward to reviewing them! |
There was a problem hiding this comment.
"Thanks again for your contributions, and we look forward to reviewing them!"
Personally I'm not a fan of these statements, as they add little substantive value but add to the text one needs to read. I'd personally not include it, but won't fight the inclusion that strongly!
There was a problem hiding this comment.
It was there before; I just moved it to the top where it was more appropriate (since it was no longer near the end where it had been) and fixed the phrasing. I can understand a concern with adding too much fluff, but I don't think sparing a single line out of well over 100 to say something welcoming is excessive, and even if not, given it would be removing something that's been in the original for years, I don't believe its worth changing now.
| CPython devguide to do so: | ||
|
|
||
| https://devguide.python.org/pullrequest/#licensing | ||
| `PSF Contributor Agreement <https://www.python.org/psf/contrib/contrib-form/>`_. |
There was a problem hiding this comment.
An interesting one, and a discussion maybe for counsel -- everything in this repo is dedicated to the public domain or CC0, so is the CLA actually needed here?
There was a problem hiding this comment.
IANAL, but the CLA still ensures contributors to affirm they own their contribution, affirms they release it under the appropriate license, and in much of the world the public domain doesn't exist, so CC0 is still a license. Its also more work to confirm it isn't necessary than to confirm that it is.
That said, it might be worth discussing, but it is well out of scope here, as these changes don't touch the substantive content, just the reST formatting, etc, and it would involve a lot more than just this file (e.g. changes to the bot, etc).
There was a problem hiding this comment.
Oh entirely out of scope but perhaps something to discuss (for the Documentation group, maybe?)
A
There was a problem hiding this comment.
IIRC I think there's already an issue open on this topic, at least for trivial commits (it wouldn't be true for the documentation as a whole)
CAM-Gerlach
force-pushed
the
update-readme-contrib-guide
branch
from
531ee4f
to
cb7c319
Compare
Some of the content in the Readme and Contributing guide is somewhat out of date. Furthermore, a number of PEPs and other resources are mentioned but not linked directly, it doesn't fully conform with the guidance in PEP 1 and PEP 12 (particularly recent changes), and there are some grammar, copyediting and reST formatting issues.
This PR fixes all that, aside from the linting additions in #2338 , the follow-up to add a section describing what edits to existing PEPs are generally considered helpful, and the removal of the outdated PEP 676 information now discussed in the
docs/subdir and/orbuild.py --help.Also, it contains a section that discusses in some detail steps to take before writing a PEP, which duplicates and is somewhat out of sync from PEP 1. Instead, I made the duplicate/outdated information more concise and general, added a bit of contributor-specific information, and referred the reader to the appropriate PEP 1 section for the rest.