|
|
9878e9d |
Contributing to Mypy
|
|
|
9878e9d |
====================
|
|
|
9878e9d |
|
|
|
9878e9d |
Welcome! Mypy is a community project that aims to work for a wide
|
|
|
9878e9d |
range of Python users and Python codebases. If you're trying Mypy on
|
|
|
9878e9d |
your Python code, your experience and what you can contribute are
|
|
|
9878e9d |
important to the project's success.
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
9878e9d |
Getting started, building, and testing
|
|
|
9878e9d |
--------------------------------------
|
|
|
9878e9d |
|
|
|
9878e9d |
If you haven't already, take a look at the project's
|
|
|
9878e9d |
[README.md file](README.md)
|
|
|
9878e9d |
and the [Mypy documentation](http://mypy.readthedocs.io/en/latest/),
|
|
|
9878e9d |
and try adding type annotations to your file and type-checking it with Mypy.
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
9878e9d |
Discussion
|
|
|
9878e9d |
----------
|
|
|
9878e9d |
|
|
|
9878e9d |
If you've run into behavior in Mypy you don't understand, or you're
|
|
|
9878e9d |
having trouble working out a good way to apply it to your code, or
|
|
|
9878e9d |
you've found a bug or would like a feature it doesn't have, we want to
|
|
|
9878e9d |
hear from you!
|
|
|
9878e9d |
|
|
|
9878e9d |
Our main forum for discussion is the project's [GitHub issue
|
|
|
9878e9d |
tracker](https://github.com/python/mypy/issues). This is the right
|
|
|
9878e9d |
place to start a discussion of any of the above or most any other
|
|
|
9878e9d |
topic concerning the project.
|
|
|
9878e9d |
|
|
|
9878e9d |
We have an IRC channel, `#python-mypy` on irc.freenode.net. This is
|
|
|
9878e9d |
lightly used, but some Mypy core developers are almost always present;
|
|
|
9878e9d |
feel free to find us there and we're happy to chat. Substantive
|
|
|
9878e9d |
technical discussion will be directed to the issue tracker.
|
|
|
9878e9d |
|
|
|
9878e9d |
#### Code of Conduct
|
|
|
9878e9d |
|
|
|
9878e9d |
Everyone participating in the Mypy community, and in particular in our
|
|
|
9878e9d |
issue tracker, pull requests, and IRC channel, is expected to treat
|
|
|
9878e9d |
other people with respect and more generally to follow the guidelines
|
|
|
9878e9d |
articulated in the [Python Community Code of
|
|
|
9878e9d |
Conduct](https://www.python.org/psf/codeofconduct/).
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
9878e9d |
Submitting Changes
|
|
|
9878e9d |
------------------
|
|
|
9878e9d |
|
|
|
9878e9d |
Even more excellent than a good bug report is a fix for a bug, or the
|
|
|
9878e9d |
implementation of a much-needed new feature. (*) We'd love to have
|
|
|
9878e9d |
your contributions.
|
|
|
9878e9d |
|
|
|
9878e9d |
(*) If your new feature will be a lot of work, we recommend talking to
|
|
|
9878e9d |
us early -- see below.
|
|
|
9878e9d |
|
|
|
9878e9d |
We use the usual GitHub pull-request flow, which may be familiar to
|
|
|
9878e9d |
you if you've contributed to other projects on GitHub. For the mechanics,
|
|
|
9878e9d |
see [our git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub),
|
|
|
9878e9d |
or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/).
|
|
|
9878e9d |
|
|
|
9878e9d |
Anyone interested in Mypy may review your code. One of the Mypy core
|
|
|
9878e9d |
developers will merge your pull request when they think it's ready.
|
|
|
9878e9d |
For every pull request, we aim to promptly either merge it or say why
|
|
|
9878e9d |
it's not yet ready; if you go a few days without a reply, please feel
|
|
|
9878e9d |
free to ping the thread by adding a new comment.
|
|
|
9878e9d |
|
|
|
9878e9d |
At present the core developers are (alphabetically):
|
|
|
9878e9d |
* David Fisher (@ddfisher)
|
|
|
9878e9d |
* Jukka Lehtosalo (@JukkaL)
|
|
|
9878e9d |
* Greg Price (@gnprice)
|
|
|
9878e9d |
* Guido van Rossum (@gvanrossum)
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
9878e9d |
Preparing Changes
|
|
|
9878e9d |
-----------------
|
|
|
9878e9d |
|
|
|
9878e9d |
Before you begin: if your change will be a significant amount of work
|
|
|
9878e9d |
to write, we highly recommend starting by opening an issue laying out
|
|
|
9878e9d |
what you want to do. That lets a conversation happen early in case
|
|
|
9878e9d |
other contributors disagree with what you'd like to do or have ideas
|
|
|
9878e9d |
that will help you do it.
|
|
|
9878e9d |
|
|
|
9878e9d |
The best pull requests are focused, clearly describe what they're for
|
|
|
9878e9d |
and why they're correct, and contain tests for whatever changes they
|
|
|
9878e9d |
make to the code's behavior. As a bonus these are easiest for someone
|
|
|
9878e9d |
to review, which helps your pull request get merged quickly! Standard
|
|
|
9878e9d |
advice about good pull requests for open-source projects applies; we
|
|
|
9878e9d |
have [our own writeup](https://github.com/python/mypy/wiki/Good-Pull-Request)
|
|
|
9878e9d |
of this advice.
|
|
|
9878e9d |
|
|
|
9878e9d |
See also our [coding conventions](https://github.com/python/mypy/wiki/Code-Conventions) --
|
|
|
9878e9d |
which consist mainly of a reference to
|
|
|
9878e9d |
[PEP 8](https://www.python.org/dev/peps/pep-0008/) -- for the code you
|
|
|
9878e9d |
put in the pull request.
|
|
|
9878e9d |
|
|
|
9878e9d |
You may also find other pages in the
|
|
|
9878e9d |
[Mypy developer guide](https://github.com/python/mypy/wiki/Developer-Guides)
|
|
|
9878e9d |
helpful in developing your change.
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
9878e9d |
Issue-tracker conventions
|
|
|
9878e9d |
-------------------------
|
|
|
9878e9d |
|
|
|
9878e9d |
We aim to reply to all new issues promptly. We'll assign a milestone
|
|
|
9878e9d |
to help us track which issues we intend to get to when, and may apply
|
|
|
9878e9d |
labels to carry some other information. Here's what our milestones
|
|
|
9878e9d |
and labels mean.
|
|
|
9878e9d |
|
|
|
9878e9d |
### Milestones
|
|
|
9878e9d |
|
|
|
9878e9d |
We use GitHub "milestones" ([see our
|
|
|
9878e9d |
list](https://github.com/python/mypy/milestones)) to roughly order
|
|
|
9878e9d |
what we want to do soon and less soon.
|
|
|
9878e9d |
|
|
|
9878e9d |
This means they represent a combination of priority and scale of work.
|
|
|
9878e9d |
Bugs that aren't a huge deal but do matter to users and don't seem
|
|
|
9878e9d |
like a lot of work to fix generally go in a near milestone; things
|
|
|
9878e9d |
that will take longer may go further out.
|
|
|
9878e9d |
|
|
|
9878e9d |
Specifically:
|
|
|
9878e9d |
|
|
|
9878e9d |
* **Numbered milestones** correspond to releases. These assignments
|
|
|
9878e9d |
are changeable, and issues may be moved earlier or later.
|
|
|
9878e9d |
Assignments to further-out milestones are more likely to
|
|
|
9878e9d |
change.
|
|
|
9878e9d |
* Point releases, like 0.x.y when we're already at 0.x.z, generally
|
|
|
9878e9d |
have issues that are less work to tackle and whose user-facing
|
|
|
9878e9d |
impact is small or a bugfix. Meatier or more radical issues
|
|
|
9878e9d |
generally go to a full "minor" release, like 0.x.0.
|
|
|
9878e9d |
* **Future** has other things we don't currently plan to get to anytime
|
|
|
9878e9d |
soon -- akin to "backlog" in some systems.
|
|
|
9878e9d |
* **Questions** is for issue threads where a user is asking a question
|
|
|
9878e9d |
but it isn't yet clear that it represents something to actually
|
|
|
9878e9d |
change. We use the issue tracker as the preferred venue for such
|
|
|
9878e9d |
questions, even when they aren't literally issues, to keep down the
|
|
|
9878e9d |
number of distinct discussion venues anyone needs to track. These
|
|
|
9878e9d |
might move to a different milestone if after discussion a bug or
|
|
|
9878e9d |
feature request emerges.
|
|
|
9878e9d |
* Issues **without a milestone** haven't been triaged. We aim to
|
|
|
9878e9d |
triage all new issues promptly, but there are some issues from 2015
|
|
|
9878e9d |
and earlier that we haven't yet reviewed for triage since adopting
|
|
|
9878e9d |
these conventions.
|
|
|
9878e9d |
|
|
|
9878e9d |
### Labels
|
|
|
9878e9d |
|
|
|
9878e9d |
* **needs discussion**: This issue needs agreement on some kind of
|
|
|
9878e9d |
design before it makes sense to implement it, and it either doesn't
|
|
|
9878e9d |
yet have a design or doesn't yet have agreement on one.
|
|
|
9878e9d |
* **feature**, **bug**, **refactoring**: These classify the user-facing
|
|
|
9878e9d |
impact of the change. Specifically "refactoring" means there should
|
|
|
9878e9d |
be no user-facing effect.
|
|
|
9878e9d |
* **duplicate**, **wontfix**: These identify issues that we've closed
|
|
|
9878e9d |
for the respective reasons.
|
|
|
9878e9d |
* **priority**, **question**, **postponed**: These labels predate the
|
|
|
9878e9d |
milestone conventions and are deprecated; they should be gone on all
|
|
|
9878e9d |
issues that have been triaged to a milestone.
|