Merge pull request #72 from brettcannon/patch-7

Various grammar tweaks

Author: Carreau

_practicalities/intro.md

@@ -8,48 +8,48 @@ id: bar
 
 We do not discourage authors to release software on Python 2. While this guide
 is mostly written with the assumption that software are going to stop Python 2
-support, it does perfectly apply to a package that wish to not support Python 3,
+support, it does perfectly apply to a package that wishes to not support Python 3,
 or is stopping support for any minor version. 
 
 
-This page gather information and links to resources allowing to release a
-library that stop supporting an older version of Python without causing too
+This page gathers information and links to resources allowing a library
+to stop supporting an older version of Python without causing too
 much disruption for users who haven't upgraded to this new version.
 
-Whether you are a user, or a developer, being aware of the issue listed here, at
-least the main points should ease lots of the pain.
+Whether you are a user or a developer, being aware of the issue listed here -- at
+least the main points -- should ease lots of the pain.
 
 # Too long, did not read:
 
  - Help and encourage users to install **pip 9.0+**
  - Help and encourage users to install **setuptools 24.3+**
- - As maintainer use `setup(..., python_requires='>=3.4')` new option.
- - do use `pip install [-e] .` and do **not** invoke `setup.py` directly.
- - **Fail** early at **install time** if on Python 2.
- - We are giving a talk at PyCon 2017 (likely recorded), add link here. 
+ - As maintainer, use the new `setup(..., python_requires='>=3.4')` option.
+ - Use `pip install [-e] .` and do **not** invoke `setup.py` directly.
+ - **Fail** early at **install time** if user is on Python 2.
+ - We are giving a talk at PyCon 2017 (likely recorded; link to follow). 
 
 ## The problem
 
-Up until December 2016 it was hard to publish a new major version of library
-that changed requirements in Python version and mark it as such so that user
+Up until December 2016 it was hard to publish a new major version of a library
+that changed requirements in Python version and mark it as such so that a user's
 system will not try to upgrade said library.
 
 With the recent changes in Python packaging this is now possible.
 
-As an example let's look at the example of the `fictitious` library.
+As an example let's look at a non-existent `fictitious` library.
 
 - `fictitious` 1.1, 1.2, 1.3, 1.4 are compatible Python 2.7 and 3.3+
 - `fictitious` 2.0 has been released and is python 3.4+ only.
 
 As a Python 2.7 user, if I don't pay attention, or if the library is not
-correctly tagged, if I issue the following:
+correctly tagged, there can be issues when you try to update the library:
 
     $ python -c 'import fictitious; print(fictitious.__version__)'
     1.3.2
     $ pip install fictitious --upgrade
 
-Either my system will install 2.0, which will not work, on the worst case
-scenario, or fail to install, in which case I will not get the critical 1.4
+Either my system will install 2.0, which will not work -- the worst case
+scenario -- or fail to install, in which case I will not get the critical 1.4
 upgrade.
 
 ## As a user
@@ -60,17 +60,17 @@ If you are already a Python 3 user, you should not encounter a lot of
 disruption. Please still check that the libraries you use follow best practices
 not to break for Python 2 users. Python is a community regardless of which
 python version you have to (or decided to) run, making sure that everything
-works make the community strong.
+works makes the community strong.
 
 Make sure you have Pip ≥ 9.0, this is especially important if you have Python
-2 installations. Having pip 9.0+ is not a guaranty to flawless upgrade. But pip
-9.0+ does have a number of safety check not available on previous versions.
+2 installations. Having pip 9.0+ is not a guarantee of a flawless upgrade. But pip
+9.0+ does have a number of safety check not available in previous versions.
 
 Having a version of pip < 9.0 can lead your system to try to upgrade to
 non-compatible versions of Python packages even if these are marked as
 non-compatible.
 
-Help as many other _users_ as possible to install pip ≥ 9.0, for the
+Help as many other _users_ as possible to install pip ≥ 9.0. For the
 transition, it is the slowest part of the ecosystem to update, and is the only
 piece that requires action of all Python users.
 
@@ -92,16 +92,16 @@ All good.
 
 ## Setuptools
 
-If you are on a system  for which no wheel is available, pip will try to
+If you are on a system for which no wheel is available, pip will try to
 install a source distribution (aka `sdist`).
 
-Installing an `sdist` will require setuptools make sure you have setuptools
-≥ 24.2.0 or building Python 3 only libraries is likely to fail. In particular
+Installing an `sdist` will require setuptools, so make sure you have setuptools
+≥ 24.2.0 or building Python 3-only libraries will likely fail. In particular
 if library authors have taken time to mark their library as Python 3 only, the
 `python_requires` argument to `setup()` may not be recognized and installation
 will fail.
 
-Use the following to check setuptools version :
+Use the following to check your setuptools version :
 
     $ python -c 'import setuptools; print(setuptools.__version__)'
     24.2.0
@@ -114,9 +114,9 @@ date system:
 ## Local package index
 
 If you are using a custom local package index, for example if you are working
-at a company with private packages, make sure it implement correctly
-[pep-503](https://www.python.org/dev/peps/pep-0503/) and let pip knows about
-the `python_requires` field. This _mostly_ mean that the html you are exposing
+at a company with private packages, make sure it correctly implements
+[pep-503](https://www.python.org/dev/peps/pep-0503/) to let pip know about
+the `python_requires` field. This _mostly_ mean that the HTML you are exposing
 should get a `data-python-requires` data attribute with the (html escaped)
 version specifier.
 
@@ -129,20 +129,20 @@ insure they support this new functionality.
 # Preparing your library
 
 
-As a library author one of the most important factor in a smooth transition is
+As a library author one of the most important factors in a smooth transition is
 planning and communication, letting your user base know in advance that the
 transition is happening and what step to take is critical for a transition.
 
 For your library code here the steps you need to take to ensure that
-installation will fail in the least number of case:
+installation will fail in the least number of cases:
 
-You need to release your new packages version with
+You need to release your package's new version with
 [setuptools](https://pypi.python.org/pypi/setuptools) version 24.2.0 or above.
-You can also use one of the alternate package manager that can set the
+You can also use one of the alternate package managers that can set the
 [Requires-Python](https://www.python.org/dev/peps/pep-0345/#requires-python)
-metadata field. Without this, pip 9.0 **will try** to install non-compatible
+metadata field. Without this, pip 9.0 **will try** to install a non-compatible
 version of your software on Python 2. This version of setuptools is recent
-(July 20, 2016) and this possible thank to the [work of Xavier
+(July 20, 2016) and this is all possible thanks to the [work of Xavier
 Fernandez](https://github.com/pypa/setuptools/pull/631)
 
 Add the following to your `setup.py`
@@ -172,19 +172,20 @@ they will get the right version of your library.
 It is recommended **not** to invoke `setup.py` directly either with `install` or
 `develop` subcommands. These may not correctly resolve dependencies, and can
 install incompatible versions of dependencies. Please recommend and use `pip
-install .`  and `pip install -e .` for regular and developer install.
+install .`  and `pip install -e .` for regular and developer installs, respectively.
 
-Check in scripts, and documentation that the correct installation command is
+Check in scripts and documentation that the correct installation command is
 used. 
 
 # Recommended Mitigations
 
 These are not mandatory but should make the transition seamless by warning your
-user early enough _and_ providing useful error messages.
+users early enough _and_ providing useful error messages.
 
 ## Runtime warning on master
 
-Add a warning at _runtime_ early on master (before switching to Python 3 only)
+Add a warning at _runtime_ that triggers early on master
+(before switching to Python 3 only)
 
 ```
 import warnings
@@ -196,19 +197,20 @@ if sys.version_info < (3,):
                   UserWarning)
 ```
 
-Your Python 2 user have a chance to upgrade, or get off master, (for example on
-the LTS branch).
+Your Python 2 users will have a chance to upgrade, or get off master,
+(for example on the LTS branch).
 
 ## Fail early at import time
 
-Add an error early at import at runtime with a clear error message, leave the
-early import compatible Python 2 for users to not be welcomed with a useless
-`SyntaxError`. Don't hesitate to use multi-line strings in error messages.
+Add an error early through import at runtime with a clear error message, leave the
+early import compatible Python 2 as users will not feel welcomed with a useless
+`SyntaxError` due to their Python 2 usage. Don't hesitate to use multi-line strings
+in error messages.
 
-Error at import time _will_ happen on system with old version of pip and
+Error at import time _will_ happen on systems with old version of pip and
 setuptools. Keep in mind that saying the package is Python 3 only is not a lot
-more helpful than a Syntax error. The most reasonable reason would be out of
-data pip and setuptools:
+more helpful than a `SyntaxError`. The most reasonable reason would be
+out-of-date pip and setuptools:
 
 
 ```
@@ -220,7 +222,7 @@ if sys.version_info < (3,):
 
 Unfortunately Frobulator 6.0 and above are not compatible with Python 2
 anymore, and you still ended up with this version installed on your system.
-That's a bummer. Sorry about that. It should not have happened. Make sure you
+That's a bummer; sorry about that. It should not have happened. Make sure you
 have pip ≥ 9.0 to avoid this kind of issues, as well as setuptools ≥ 24.2:
 
  $ pip install pip setuptools --upgrade
@@ -247,14 +249,15 @@ https://i.am.an/url
 ## Watch out for beta releases
 
 
-Make sure your version number match pep 440 or you will get surprises during
-beta in particular as the `sdist` and `wheel` will appear as being different
-versions, in particular sdist (during beta/rc/post) can appear with a greater
-version number than wheels. Pip thus try to install the sdist instead of the
-wheel, which have more chance of failing, in particular with pre 24.2 versions
-of setuptools.
+Make sure your version number matches
+[PEP 440](https://www.python.org/dev/peps/pep-0440/) or you will get surprises
+during beta, in particular as the `sdist` and `wheel` will appear as being
+different versions (the sdist (during beta/rc/post) can appear with
+a greater version number than wheels). Pip thus will try to install the sdist
+instead of the wheel, which has more chance of failing, in particular with
+pre-24.2 versions of setuptools.
 
-The regular expression to check for validity of pep440 can be find below:
+The regular expression to check for validity of pep440 can be found below:
 
     ^
     ([1-9]\\d*!)?
@@ -268,11 +271,11 @@ The regular expression to check for validity of pep440 can be find below:
 ## fail early in setup.py
 
 Leave `setup.py` python 2 compatible and fail early. If you detect Python 2
-raise a clear error message and ask user to make sure they have pip > 9.0 (or
+raise a clear error message and ask the user to make sure they have pip > 9.0 (or
 migrate to Python 3). You can (try to) conditionally import pip and check for
 its version but this might not be the same pip. Failing early is important to
 make sure the Python installation does not install an incompatible version.
-Otherwise user code can fail at runtime arbitrary later in the future, which can
+Otherwise user code can fail at runtime arbitrarily later in the future, which can
 be a difficult to debug and fix. Get inspiration from the message of failure at
 runtime, and adapt for installation time.
 
@@ -281,7 +284,7 @@ runtime, and adapt for installation time.
 If you control dependant packages, Make sure to include conditional dependencies
 depending on the version of Python.
 
-# Non recommended mitigations
+# Non-recommended mitigations
 
 This is a collection of "mitigation" or "solutions" you will find on the web
 and that you will hear about. This is an attempt to acknowledge them, and
@@ -290,65 +293,66 @@ implement them.
 
 ### Use a meta-package.
 
-It is possible to release a meta-package that has _virtually_ no code and rely
-on conditional dependency to install its actual core code on the user system.
+It is possible to release a meta-package that has _virtually_ no code and relies
+on a conditional dependency to install its actual core code on the user system.
 For example, Frob-6.0 could be a meta-package which depends on
 Frob-real-py2 on Python < 3.0, and Frob-real-py3 on Python ≥ 3.4. While
 this approach is _doable_ this can make imports confusing.
 
 ## Depend on setuptools
 
-You can mark your library as dependent on setuptools greater than 24.3 this
+You can mark your library as dependent on setuptools greater than 24.3 as this
 will insure that during the next upgrade (when the packages drop python 2
 support) will have the right version of setuptools.
 
 Of course regardless of all the care you will take for your library to no break
-and to install only on python 2, you will likely have cases where it still end
-up being installed on incompatible versions of Python. Simply because users
-upgrades rarely and only an old version of pip or setuptools is enough to make
-the all update process broken.
+and to install only on python 2, you will likely have cases where it will still
+end up being installed on incompatible versions of Python. Simply because users
+upgrade rarely and only an old version of pip or setuptools is enough to make
+the update process broken.
 
 Plus setuptools is rarely an actual dependency of your project but a
 requirement to build wheels.
 
 
-### Multiple Sdist.
+### Multiple sdist files
 
 Pip (used to) support a "feature" where a sdist ending in `-pyX.Y.tar.gz` would
 only be seen as compatible on Python X.Y, thus it used to be possible to
 publish multiple sdist of a package targeting various python version.
 
-Though it is not possible anymore to upload multiple sdist on PyPI. This
-solution is thus not possible.
+It is not possible anymore to upload multiple sdist files on PyPI, so this
+solution is no longer tenable.
 
 ### Wheel only ?
 
-Releasing a package only using wheel for a given python version is doable, but
+Releasing a package only using wheels for a given python version is doable, but
 this will break downstream packages that may require the original source to
-reproduce the build.
+reproduce their build.
 
-# Why all that ?
+# Why all *this* ?!?
 
-You might wonder why all this, it's 2016 already, so how come all these
-issues ? Python 3 has been out for 8+ years now !
+You might wonder why all this, it's 2016 already, so how come this is now an 
+issue ? Python 3 has been out for 8+ years now !
 
-Well there are many reasons to this, first of all, this issue mostly affect
+Well there are many reasons for this. First of all, this issue mostly affects
 libraries that are currently python 2 and Python 3 compatible at the same time.
 Many libraries have transitioned from Python 2-only to Python 2 + 3. And the
 issue of transitioning to Python 3 only is relatively recent. Technically it
-can also apply to libraries that are only stopping support for 2.6, or even are
-already Python 3 only, but are starting to stop support for earlier versions of
-Python. For example a library releasing a Python 3.4+ only version.
+can also apply to libraries that are only stopping support for 2.6, or are even
+already Python 3 only, but are starting to stop supporting earlier versions of
+Python (for example a library releasing a Python 3.4+ only version).
 
-Python 3.3 was release at the end of 2012, and was the first version to
+Python 3.3 was released at the end of 2012, and was the first version to
 support (again) `u` as a prefix for Unicode string. It was one of the first
-minor version of Python 3 that saw a majority of single-source project working
-both on Python 2 and Python 3. These are the Project that will likely be
+minor versions of Python 3 that saw a majority of single-source projects working
+both on Python 2 and Python 3. These are the projects that will likely be
 affected by this issue.
 
-The introduction of Python 3 was chaotic, there are still strong argument both
-in Python 2 and Python 3 camps. In the one suffering the most from this are
-users. Starting with the fact that inevitably some libraries will stop support
-for Python 2 and release Python 3 only library. And that inevitably some system
-will will not be upgraded to Python 3 how can we _ensure_ that users get the
-_least_ breakage as possible ? And what are the best practices to follow.
+The introduction of Python 3 was chaotic; there are still strong arguments in both
+the Python 2 and Python 3 camps. Regardless of what side you take, the ones suffering
+the most from this are users (starting with the fact that inevitably some libraries
+will stop supporting for Python 2 and release Python 3 only library). Inevitably, some
+systems and people will will not be upgraded to Python 3, so this document hopefully
+helps to _ensure_ that users get the _least_ breakage as possible and what are the best
+practices are to follow.