Commits

Anonymous committed fdbe2a3

proof-read contributing

Comments (0)

Files changed (1)

source/contributing.txt

 
 Tools like :ref:`Pip <pip_info>` or `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ are using PyPI as the default location to find :term:`distributions <distribution>` to install. When ``pip install Foo`` is called, it will browse PyPI to find the latest available version of the ``Foo`` project using `The Simple Index Protocol`_. If it finds it, it will download it and install it automatically.
 
-This automatic installation ala :ref:`pip_info` will work only if the distribution is using the Distutils-based structure and containes a ``setup.py`` file.
+This automatic installation ala :ref:`pip_info` will work only if the distribution is using the Distutils-based structure and contains a ``setup.py`` file.
 
-This involves that any serious Python project should use Distutils
+This means that any serious Python project should use Distutils
 (see the :ref:`basics <creation_basics>` for doing this)
 and should at the minimum be registered at PyPI. Uploading releases there is
 also a good practice.
 Registering projects
 --------------------
 
-Registering a project at PyPI is done by using :term:`Distutils`' ``register`` command. This command performs a simple HTTP post using a basic authentication.
-It will use for that the login name and password stored in the ``.pypirc`` file
+Registering a project at PyPI is done by using :term:`Distutils`' ``register`` command. This command performs a simple HTTP post using basic authentication
+with the login name and password stored in the ``.pypirc`` file
 located in your home directory. This login has to be registered at PyPI, so
-you need to go there and create an account.
+you should go there and create an account before running ``register`` for the first time.
 
 Another option is to call ``register`` once on any Distutils-based project.
 It will register the new account for you and all you'll have to do is to reply
 
 .. note::
 
-    A recent GSOC project called Keyring was done in 2009 in order
+    A recent GSoC project called Keyring was created in 2009 in order
     to use any available system keyring like KWallet or KeyChain to
-    be able to store the PyPI password there. The project was coded
-    and once its proven to be mature enough, it might be used in Distutils
-    ``register`` and ``upload`` commands.
+    store the PyPI password. The project exists and may be used in Distutils
+    by the ``register`` and ``upload`` commands.
 
     See: http://pypi.python.org/pypi/keyring
 
-Once your account is ready, registering it at PyPI will create among other
-things a new web page there, using the metadata fields of your project.
+Once your account is ready, registering it at PyPI will create
+a new web page there, using the metadata fields of your project.
 
 - **name** will be used as the unique identifier in PyPI. For example, if
   your project's name is ``Foo``, its page will be located at
 
 A good practice is to use reST, and make sure your ``long_description``
 field doesn't contain any reStructuredText syntax error. See
-:ref:`rest_example` for a quick introduction on how to write a reSt compatible field.
+:ref:`rest_example` for a quick introduction on how to write a reST compatible field.
 
 To perform a check, install ``docutils`` by using Pip
 (``pip install docutils``) and run::
 
     $ python.exe setup.py --long-description | rst2html.py > dummy.html
 
-If you text contains any reSt error or warning, they will be displayed.
+If your text contains any reST error or warning, they will be displayed.
 
 Starting at Python 2.7, you can use the ``check`` command instead of calling
 the ``rst2html.py`` script, as long as ``docutils`` is installed::
 Uploading distributions
 -----------------------
 
-PyPI also allows developer to upload their project's distributions. This can
+PyPI also allows developers to upload their project's distributions. This can
 be done manually via a web form, but also through Distutils by using the
 ``upload`` command.
 
 
     $ pip install distribute
 
-Will look at the ``http://pypi.python.org/simple/distribute`` page, which
-is a list of URLs for the Distribute project. These URLs are:
+will look at the ``http://pypi.python.org/simple/distribute`` page, which
+is a list of URLs for the Distribute project. These URLs include:
 
-- the Distribute archives uploaded at PyPI
-- a link to the project's home page
-- extra links contained in the project's description fields
+ - the Distribute archives uploaded at PyPI
+ - a link to the project's home page
+ - extra links contained in the project's description fields
 
 The Package Index follows these rules (taken from Setuptools' documentation):
 
 Limitations of the system
 -------------------------
 
-Within the last years, PyPI became a first class citizen in the Python
-developement ecosystem. For instance Plone developers that are using
-``zc.buildout`` to install Plone-based applications, are making hundreds
-of calls to PyPI each time they build their projects. That's because a web
-application is using hundreds of small Python distributions nowadays.
+Within the last few years, PyPI has become a first class citizen in the Python
+development ecosystem. For instance Plone developers that are using
+``zc.buildout`` to install Plone-based applications are making hundreds
+of calls to PyPI each time they build their projects. That's because many web
+applications are using hundreds of small Python distributions nowadays.
 
 This has a bad side effect: if PyPI is down, it becomes impossible to build
 some applications. PyPI acts as a ``Single Point of Failure`` (SPOF).
 
-The PyPI server is quite robust and its uptime is probably around 99.99%.
-Although people hit the SPOF problem once or twice per year. The community
-started to develop strategies to avoid it:
+The PyPI server is quite robust and its uptime is probably around 99.99%,
+although people hit the SPOF problem once or twice per year. The community
+has started to develop strategies to avoid it:
 
-- ``zc.buildout`` comes with a cache that will keep on the system a copy
-  of downloaded archives. This avoid getting packages at PyPI when they were
+- ``zc.buildout`` comes with a cache that will keep a copy
+  of downloaded archives on the local system. This avoids getting packages at PyPI when they were
   already downloaded once.
 
 - the `collective.eggproxy <http://pypi.python.org/pypi/collective.eggproxy>`_
   is a mirroring script that syncs a local copy of the simple index so tools
   can use it instead of calling PyPI.
 
-During last year, PEP 381 was added to try describe a mirroring protocol and
-set up a system of official ring of PyPI mirrors. This system should be ready
-by the end of the year 2010, and will provide a DNS at ``mirrors.pypi.org``
+In the last year, PEP 381 was added to describe a mirroring protocol and
+set up an official "ring" of PyPI mirrors. This system should be ready
+by the end of the year 2010, and will provide a DNS entry under ``mirrors.pypi.org``
 listing all mirrors IPs. This will allow tools like :ref:`pip_info` to
 list all mirrors and pick the closest one, or fall back in case a server is
 down.