Change to -stubs over _stubs (#568)

Also note that a py.typed file is not needed for stub only packages.

Author: emmatyping

pep-0561.rst

@@ -131,9 +131,10 @@ type information, it is preferred that the ``*.pyi`` stubs are alongside the
 corresponding ``*.py`` files. However, the stubs can also be put in a separate
 package and distributed separately. Third parties can also find this method
 useful if they wish to distribute stub files. The name of the stub package
-MUST follow the scheme ``foopkg_stubs`` for type stubs for the package named
-``foopkg``. The normal resolution order of checking ``*.pyi`` before ``*.py``
-will be maintained.
+MUST follow the scheme ``foopkg-stubs`` for type stubs for the package named
+``foopkg``. Note that for stub only packages adding a py.typed marker is not
+needed since the name ``*-stubs`` is enough to indicate it is a source of typing
+information.
 
 Third parties seeking to distribute stub files are encouraged to contact the
 maintainer of the package about distribution alongside the package. If the
@@ -143,9 +144,13 @@ inline, then a third party stub only package can be created.
 In addition, stub-only distributions SHOULD indicate which version(s)
 of the runtime package are supported by indicating the runtime distribution's
 version(s) through normal dependency data. For example, the
-stub package ``flyingcircus_stubs`` can indicate the versions of the
+stub package ``flyingcircus-stubs`` can indicate the versions of the
 runtime ``flyingcircus`` distribution it supports through ``install_requires``
-in distutils-based tools, or the equivalent in other packaging tools.
+in distutils-based tools, or the equivalent in other packaging tools. Note that
+in pip 9.0, if you update ``flyingcircus-stubs``, it will update
+``flyingcircus``. In pip 9.0, you can use the
+``--upgrade-strategy=only-if-needed`` flag. In pip 10.0 this is the default
+behavior.
 
 
 Type Checker Module Resolution Order
@@ -161,7 +166,7 @@ resolve modules containing type information:
    stubs to use, and patch broken stubs/inline types from packages.
 
 3. Stub packages - these packages can supersede the installed packages.
-   They can be found at ``foopkg_stubs`` for package ``foopkg``.
+   They can be found at ``foopkg-stubs`` for package ``foopkg``.
 
 4. Inline packages - if there is nothing overriding the installed
    package, and it opts into type checking, inline types SHOULD be used.
@@ -176,6 +181,9 @@ of that Python version. This can be queried e.g.
 that the type checker allow for the user to point to a particular Python
 binary, in case it is not in the path.
 
+The normal resolution order of checking ``*.pyi`` before ``*.py``
+will be maintained.
+
 
 Implementation
 ==============
@@ -198,6 +206,12 @@ Smith, and Guido van Rossum.
 Version History
 ===============
 
+* 2018-02-02
+
+    * Change stub only package suffix to be -stubs not _stubs.
+    * Note that py.typed is not needed for stub only packages.
+    * Add note about pip and upgrading stub packages.
+
 * 2017-11-12
 
     * Rewritten to use existing tooling only