Guidelines pre-PEP: add One header, Naming, Language support #51
Conversation
| You can deprecate and remove the old version following Python's | ||
| :pep:`backwards compatibility policy <387>`. | ||
|
|
||
| After API has been removed, do not reuse the old name, |
There was a problem hiding this comment.
It could be helpful to have a list of "retired" names to check for conflicts.
There was a problem hiding this comment.
Yes. On the other hand,
- I don't think it's too likely that someone reuses a name accidentally, and
- if they do, it's not a big problem. [edit: added forgotten “not”]
The main point is that you shouldn't intentionally retire API to make its name available.
|
Looks good; I added a few minor remarks. |
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
guidelines.rst
Outdated
| that is, the types of all arguments must be specified. | ||
|
|
||
| Argument *names* should generally be included in declarations, | ||
| but may be omitted if the meaning is obvious. |
There was a problem hiding this comment.
Do we gain anything from this? Might as well just require it, IMHO. And should we require that names match the definition? (I suppose allowing variation saves us from PRs making fixes to our existing inconsistencies...)
There was a problem hiding this comment.
This is purely for humans that read the headers.
More than definitions, I'd care about matching the documentation :)
I don't think we'll be enforcing this, except if someone adds an inscrutable chunk of API. It's easy enough to fix later.
Hence the weasel words.
This document is for new API, I don't plan PRs to fix inconsistencies.
(For definitions: if there's an argument PyObject *x, I'd be OK with the definition calling it x_obj, type-check it, and have PyLongObject *x be the cast version.)
There was a problem hiding this comment.
I don't plan PRs to fix inconsistencies.
I know you don't, but we'll get other people who will come along and create PRs to fix things that don't match new guidelines.
Maybe it's best to just say nothing?
There was a problem hiding this comment.
OK. PEP-7 would be a better place for this, anyway.
guidelines.rst
Outdated
| that is, the types of all arguments must be specified. | ||
|
|
||
| Argument *names* should generally be included in declarations, | ||
| but may be omitted if the meaning is obvious. |
There was a problem hiding this comment.
This is purely for humans that read the headers.
More than definitions, I'd care about matching the documentation :)
I don't think we'll be enforcing this, except if someone adds an inscrutable chunk of API. It's easy enough to fix later.
Hence the weasel words.
This document is for new API, I don't plan PRs to fix inconsistencies.
(For definitions: if there's an argument PyObject *x, I'd be OK with the definition calling it x_obj, type-check it, and have PyLongObject *x be the cast version.)
|
Thank you for the reviews, everyone! |
Hello,
Here are a few more proposed sections for the upcoming guidelines PEP.
@zooba @vstinner @erlend-aasland @serhiy-storchaka @mdboom, please add your comments or approvals.
I'd like to avoid growing the scope of this PR. For substantial additions, or things that need more discussion, there's a TODO list in #44.
If a section is controversial I can delete it for now.