|
| 1 | +# Contributing to typeshed |
| 2 | + |
| 3 | +Welcome! typeshed is a community project that aims to work for a wide |
| 4 | +range of Python users and Python codebases. If you're trying a type |
| 5 | +checker on your Python code, your experience and what you can contribute |
| 6 | +are important to the project's success. |
| 7 | + |
| 8 | + |
| 9 | +## The contribution process at a glance |
| 10 | + |
| 11 | +1. Read the [README.md file](README.md). |
| 12 | +2. Set up your environment to be able to run all tests with `runtests.sh`. They should pass. |
| 13 | +3. [Prepare your changes](#preparing-changes): |
| 14 | + * [Contact us](#discussion) before starting significant work. |
| 15 | + * IMPORTANT: For new libraries, [get permission from the library owner first](#adding-a-new-library). |
| 16 | + * Create your stubs [conforming to the coding style](#stub-file-coding-style). |
| 17 | + * Make sure `runtests.sh` passes cleanly on Mypy, pytype, and flake8. |
| 18 | +4. [Submit your changes](#submitting-changes): |
| 19 | + * Open a pull request |
| 20 | + * For new libraries, [include a reference to where you got permission](#adding-a-new-library) |
| 21 | +5. You can expect a reply within a few days: |
| 22 | + * Diffs are merged when considered ready by the core team. |
| 23 | + * Feel free to ping the core team if your pull request goes without |
| 24 | + a reply for more than a few days. |
| 25 | + |
| 26 | +For more details, read below. |
| 27 | + |
| 28 | + |
| 29 | +## Discussion |
| 30 | + |
| 31 | +If you've run into behavior in the type checker that suggests the type |
| 32 | +stubs for a given library are incorrect or incomplete, or a library you |
| 33 | +depend on is missing type annotations, we want to hear from you! |
| 34 | + |
| 35 | +Our main forum for discussion is the project's [GitHub issue |
| 36 | +tracker](https://github.com/python/typeshed/issues). This is the right |
| 37 | +place to start a discussion of any of the above or most any other |
| 38 | +topic concerning the project. |
| 39 | + |
| 40 | +For less formal discussion, try the Mypy chat room on |
| 41 | +[gitter.im](https://gitter.im/python/mypy). Some Mypy core developers |
| 42 | +are almost always present; feel free to find us there and we're happy |
| 43 | +to chat. Substantive technical discussion will be directed to the |
| 44 | +issue tracker. |
| 45 | + |
| 46 | +### Code of Conduct |
| 47 | + |
| 48 | +Everyone participating in the typeshed community, and in particular in |
| 49 | +our issue tracker, pull requests, and IRC channel, is expected to treat |
| 50 | +other people with respect and more generally to follow the guidelines |
| 51 | +articulated in the [Python Community Code of |
| 52 | +Conduct](https://www.python.org/psf/codeofconduct/). |
| 53 | + |
| 54 | + |
| 55 | +## Submitting Changes |
| 56 | + |
| 57 | +Even more excellent than a good bug report is a fix for a bug, or the |
| 58 | +implementation of a much-needed stub. We'd love to have |
| 59 | +your contributions. |
| 60 | + |
| 61 | +We use the usual GitHub pull-request flow, which may be familiar to |
| 62 | +you if you've contributed to other projects on GitHub. For the |
| 63 | +mechanics, see [Mypy's git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), |
| 64 | +or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). |
| 65 | + |
| 66 | +Anyone interested in type stubs may review your code. One of the core |
| 67 | +developers will merge your pull request when they think it's ready. |
| 68 | +For every pull request, we aim to promptly either merge it or say why |
| 69 | +it's not yet ready; if you go a few days without a reply, please feel |
| 70 | +free to ping the thread by adding a new comment. |
| 71 | + |
| 72 | +At present the core developers are (alphabetically): |
| 73 | +* David Fisher (@ddfisher) |
| 74 | +* Łukasz Langa (@ambv) |
| 75 | +* Jukka Lehtosalo (@JukkaL) |
| 76 | +* Matthias Kramm (@matthiaskramm) |
| 77 | +* Greg Price (@gnprice) |
| 78 | +* Guido van Rossum (@gvanrossum) |
| 79 | + |
| 80 | + |
| 81 | +## Preparing Changes |
| 82 | + |
| 83 | +### Before you begin |
| 84 | + |
| 85 | +If your change will be a significant amount of work to write, we highly |
| 86 | +recommend starting by opening an issue laying out what you want to do. |
| 87 | +That lets a conversation happen early in case other contributors disagree |
| 88 | +with what you'd like to do or have ideas that will help you do it. |
| 89 | + |
| 90 | +### Adding a new library |
| 91 | + |
| 92 | +If you want to submit type stubs for a new library, you need to |
| 93 | +**contact the maintainers of the original library** first to let them |
| 94 | +know and **get their permission**. Do it by opening an issue on their |
| 95 | +project's bug tracker. This gives them the opportunity to |
| 96 | +consider adopting type hints directly in their codebase (which you |
| 97 | +should prefer to external type stubs). When the project owners agree |
| 98 | +for you to submit stubs here, open a pull request **referencing the |
| 99 | +message where you received permission**. |
| 100 | + |
| 101 | +Make sure your changes pass tests by running ``runtests.sh`` (the |
| 102 | +[README](README.md) has more information). |
| 103 | + |
| 104 | +### Using stubgen |
| 105 | + |
| 106 | +Mypy includes a tool called [stubgen](https://github.com/python/mypy/blob/master/mypy/stubgen.py) |
| 107 | +that you can use as a starting point for your stubs. Note that this |
| 108 | +generator is currently unable to determine most argument and return |
| 109 | +types and omits them or uses ``Any`` in their place. Fill out the types |
| 110 | +that you know. Leave out modules that you are not using at all. It's |
| 111 | +strictly better to provide partial stubs that have detailed type |
| 112 | +information than to submit unmodified ``stubgen`` output for an entire |
| 113 | +library. |
| 114 | + |
| 115 | +### Stub file coding style |
| 116 | + |
| 117 | +Stub files are *like* Python files and you should generally expect them |
| 118 | +to look the same. Your tools should be able to successfully treat them |
| 119 | +as regular Python files. However, there are a few important differences |
| 120 | +you should know about. |
| 121 | + |
| 122 | +Style conventions for stub files are different from PEP 8. The general |
| 123 | +rule is that they should be as concise as possible. Specifically: |
| 124 | +* there is no line length limit; |
| 125 | +* prefer long lines over elaborate indentation; |
| 126 | +* prefer ``...`` over ``pass``; |
| 127 | +* prefer ``...`` on the same line as the class/function signature; |
| 128 | +* avoid vertical whitespace between consecutive module-level functions, |
| 129 | + names, or methods and fields within a single class; |
| 130 | +* prefer type comments over variable annotations unless your stubs are |
| 131 | + exclusively targeting Python 3.6. |
| 132 | + |
| 133 | +Imports in stubs are considered private (not part of the exported API) |
| 134 | +unless: |
| 135 | +* they use the form ``from library import name as name`` (sic, using |
| 136 | + explicit ``as`` even if the name stays the same); or |
| 137 | +* they use the form ``from library import *`` which means all names |
| 138 | + from that library are exported. |
| 139 | + |
| 140 | +Stub files support forward references natively. In other words, the |
| 141 | +order of class declarations and type aliases does not matter in |
| 142 | +a stub file. You can also use the name of the class within its own |
| 143 | +body. Focus on making your stubs clear to the reader. Avoid using |
| 144 | +string literals in type annotations. |
| 145 | + |
| 146 | +Finally, remember to include a comment on the top of your file about the |
| 147 | +version of the Python language your stubs were tested against and |
| 148 | +version of the library they were built for. This makes it easier to |
| 149 | +maintain the stubs in the future. |
| 150 | + |
| 151 | +NOTE: there are stubs in this repository that don't conform to the |
| 152 | +style described above. Fixing them is a great starting point for new |
| 153 | +contributors. |
| 154 | + |
| 155 | +### What to do when a project's documentation and implementation disagree |
| 156 | + |
| 157 | +Type stubs are meant to be external type annotations for a given |
| 158 | +library. While they are useful documentation in its own merit, they |
| 159 | +augment the project's concrete implementation, not the project's |
| 160 | +documentation. Whenever you find them disagreeing, model the type |
| 161 | +information after the actual implementation and file an issue on the |
| 162 | +project's tracker to fix their documentation. |
| 163 | + |
| 164 | +## Issue-tracker conventions |
| 165 | + |
| 166 | +We aim to reply to all new issues promptly. We'll assign a milestone |
| 167 | +to help us track which issues we intend to get to when, and may apply |
| 168 | +labels to carry some other information. Here's what our milestones |
| 169 | +and labels mean. |
| 170 | + |
| 171 | +### Labels |
| 172 | + |
| 173 | +* **needs discussion**: This issue needs agreement on some kind of |
| 174 | + design before it makes sense to implement it, and it either doesn't |
| 175 | + yet have a design or doesn't yet have agreement on one. |
| 176 | +* **help wanted**: This issue could use a volunteer willing to implement |
| 177 | + it. Those issues can be great starting points for new contributors! |
| 178 | +* **enhancement**, **bug**, **refactoring**: These classify the |
| 179 | + user-facing impact of the change. Specifically "refactoring" means |
| 180 | + there should be no user-facing effect. |
| 181 | +* **duplicate**, **wontfix**: These identify issues that we've closed |
| 182 | + for the respective reasons. |
0 commit comments