Add content from typeshed/CONTRIBUTING.md #1882
Conversation
docs/guides/writing_stubs.rst
Outdated
| @@ -113,18 +118,6 @@ Stub Content | |||
| This section documents best practices on what elements to include or | |||
| leave out of stub files. | |||
|
|
|||
| Modules excluded fom stubs | |||
There was a problem hiding this comment.
I moved this down cuz it felt weird for the "stub content" section to start with "what you shouldn't include"
| Avoid invariant collection types (`list`, `dict`) for function parameters, | ||
| in favor of covariant types like `Mapping` or `Sequence`. | ||
|
|
||
| Avoid union return types. See https://github.com/python/mypy/issues/1693 |
There was a problem hiding this comment.
Probably for a future PR, but it would be nice if the content of python/mypy#1693 and python/mypy#7214 below could be copied into the guides. Having pieces of general typing advice hidden away in mypy issues feels sort of odd.
There was a problem hiding this comment.
Looks good to me aside from a couple minor comments.
@JelleZijlstra Do you want to review this as well?
Co-authored-by: Rebecca Chen <[email protected]>
Co-authored-by: Rebecca Chen <[email protected]>
… suppression formats section
|
|
||
| Keep the deprecation message concise, but try to mention the projected | ||
| version when the functionality is to be removed, and a suggested | ||
| replacement. |
There was a problem hiding this comment.
Should we say that if a deprecated feature is still very widely used and was deprecated only recently, it may be best to wait before adding @deprecated?
There was a problem hiding this comment.
I don't think so. If the feature is still in wide use, that's an argument against deprecating the feature, but if the runtime code decides to deprecate something, the stubs should communicate that fact.
Removed repeated example, fixed formatting, removed stray "the".
|
Looks like all comments have been addressed. I did one more style/formatting pass. Thanks @yangdanny97! |
This PR merges non-typeshed-specific content on writing stubs into main typing guide.
https://github.com/python/typeshed/blob/main/CONTRIBUTING.md
This would let us reference this guide from typeshed's CONTRIBUTING.md and delete the duplicate sections.
#1880