Commit 81bfa5f5 authored by manas kashyap's avatar manas kashyap 💬

New upstream version 18.1

parent 5c6fb4c2
......@@ -12,6 +12,7 @@ Alexandre Conrad <alexandre.conrad@gmail.com>
Alli <alzeih@users.noreply.github.com>
Anatoly Techtonik <techtonik@gmail.com>
Andrei Geacar <andrei.geacar@gmail.com>
Andrew Gaul <andrew@gaul.org>
Andrey Bulgakov <mail@andreiko.ru>
Andrés Delfino <34587441+andresdelfino@users.noreply.github.com>
Andrés Delfino <adelfino@gmail.com>
......@@ -36,6 +37,8 @@ Ashley Manton <ajd.manton@googlemail.com>
Atsushi Odagiri <aodagx@gmail.com>
Avner Cohen <israbirding@gmail.com>
Baptiste Mispelon <bmispelon@gmail.com>
Barney Gale <barney.gale@gmail.com>
barneygale <barney.gale@gmail.com>
Bartek Ogryczak <b.ogryczak@gmail.com>
Bastian Venthur <mail@venthur.de>
Ben Darnell <ben@bendarnell.com>
......@@ -46,6 +49,7 @@ Benjamin VanEvery <ben@simondata.com>
Benoit Pierre <benoit.pierre@gmail.com>
Berker Peksag <berker.peksag@gmail.com>
Bernardo B. Marques <bernardo.fire@gmail.com>
Bernhard M. Wiedemann <bwiedemann@suse.de>
Bogdan Opanchuk <bogdan@opanchuk.net>
Brad Erickson <eosrei@gmail.com>
Bradley Ayers <bradley.ayers@gmail.com>
......@@ -55,6 +59,7 @@ Brian Rosner <brosner@gmail.com>
BrownTruck <BrownTruck@users.noreply.github.com>
Bruno Oliveira <nicoddemus@gmail.com>
Bruno Renié <brutasse@gmail.com>
Bstrdsmkr <bstrdsmkr@gmail.com>
Buck Golemon <buck@yelp.com>
burrows <burrows@preveil.com>
Bussonnier Matthias <bussonniermatthias@gmail.com>
......@@ -157,6 +162,7 @@ Herbert Pfennig <herbert@albinen.com>
Hsiaoming Yang <lepture@me.com>
Hugo <hugovk@users.noreply.github.com>
Hugo Lopes Tavares <hltbra@gmail.com>
hugovk <hugovk@users.noreply.github.com>
Hynek Schlawack <hs@ox.cx>
Ian Bicking <ianb@colorstudy.com>
Ian Cordasco <graffatcolmingov@gmail.com>
......@@ -182,6 +188,7 @@ Jannis Leidel <jannis@leidel.info>
jarondl <me@jarondl.net>
Jason R. Coombs <jaraco@jaraco.com>
Jay Graves <jay@skabber.com>
Jean-Christophe Fillion-Robin <jchris.fillionr@kitware.com>
Jeff Barber <jbarber@computer.org>
Jeff Dairiki <dairiki@dairiki.org>
Jeremy Stanley <fungi@yuggoth.org>
......@@ -194,6 +201,7 @@ Jon Dufresne <jon.dufresne@gmail.com>
Jon Parise <jon@indelible.org>
Jon Wayne Parrott <jjramone13@gmail.com>
Jonas Nockert <jonasnockert@gmail.com>
Jonathan Herbert <foohyfooh@gmail.com>
Joost Molenaar <j.j.molenaar@gmail.com>
Jorge Niedbalski <niedbalski@gmail.com>
Joseph Long <jdl@fastmail.fm>
......@@ -219,10 +227,12 @@ kpinc <kop@meme.com>
Kumar McMillan <kumar.mcmillan@gmail.com>
Kyle Persohn <kyle.persohn@gmail.com>
Laurent Bristiel <laurent@bristiel.com>
Laurie Opperman <laurie@sitesee.com.au>
Leon Sasson <leonsassonha@gmail.com>
Lev Givon <lev@columbia.edu>
Lincoln de Sousa <lincoln@comum.org>
Lipis <lipiridis@gmail.com>
Loren Carvalho <lcarvalho@linkedin.com>
Lucas Cimon <lucas.cimon@gmail.com>
Ludovic Gasc <gmludo@gmail.com>
Luke Macken <lmacken@redhat.com>
......@@ -259,6 +269,7 @@ Michael E. Karpeles <michael.karpeles@gmail.com>
Michael Klich <michal@michalklich.com>
Michael Williamson <mike@zwobble.org>
michaelpacer <michaelpacer@gmail.com>
Mickaël Schoentgen <mschoentgen@nuxeo.com>
Miguel Araujo Perez <miguel.araujo.perez@gmail.com>
Mihir Singh <git.service@mihirsingh.com>
Min RK <benjaminrk@gmail.com>
......@@ -272,6 +283,7 @@ Nehal J Wani <nehaljw.kkd1@gmail.com>
Nick Coghlan <ncoghlan@gmail.com>
Nick Stenning <nick@whiteink.com>
Nikhil Benesch <nikhil.benesch@gmail.com>
Nitesh Sharma <nbsharma@outlook.com>
Nowell Strite <nowell@strite.org>
nvdv <modestdev@gmail.com>
Ofekmeister <ofekmeister@gmail.com>
......@@ -380,6 +392,7 @@ Tomer Chachamu <tomer.chachamu@gmail.com>
Tony Zhaocheng Tan <tony@tonytan.io>
Toshio Kuratomi <toshio@fedoraproject.org>
Travis Swicegood <development@domain51.com>
Tzu-ping Chung <uranusjr@gmail.com>
Valentin Haenel <valentin.haenel@gmx.de>
Victor Stinner <victor.stinner@gmail.com>
Viktor Szépe <viktor@szepe.net>
......
......@@ -3,10 +3,57 @@
fix problems like typo corrections or such.
To add a new change log entry, please see
https://pip.pypa.io/en/latest/development/#adding-a-news-entry
https://pip.pypa.io/en/latest/development/contributing/#news-entries
.. towncrier release notes start
18.1 (2018-10-05)
=================
Features
--------
- Allow PEP 508 URL requirements to be used as dependencies.
As a security measure, pip will raise an exception when installing packages from
PyPI if those packages depend on packages not also hosted on PyPI.
In the future, PyPI will block uploading packages with such external URL dependencies directly. (`#4187 <https://github.com/pypa/pip/issues/4187>`_)
- Upgrade pyparsing to 2.2.1. (`#5013 <https://github.com/pypa/pip/issues/5013>`_)
- Allows dist options (--abi, --python-version, --platform, --implementation) when installing with --target (`#5355 <https://github.com/pypa/pip/issues/5355>`_)
- Support passing ``svn+ssh`` URLs with a username to ``pip install -e``. (`#5375 <https://github.com/pypa/pip/issues/5375>`_)
- pip now ensures that the RECORD file is sorted when installing from a wheel file. (`#5525 <https://github.com/pypa/pip/issues/5525>`_)
- Add support for Python 3.7. (`#5561 <https://github.com/pypa/pip/issues/5561>`_)
- Malformed configuration files now show helpful error messages, instead of tracebacks. (`#5798 <https://github.com/pypa/pip/issues/5798>`_)
Bug Fixes
---------
- Checkout the correct branch when doing an editable Git install. (`#2037 <https://github.com/pypa/pip/issues/2037>`_)
- Run self-version-check only on commands that may access the index, instead of
trying on every run and failing to do so due to missing options. (`#5433 <https://github.com/pypa/pip/issues/5433>`_)
- Allow a Git ref to be installed over an existing installation. (`#5624 <https://github.com/pypa/pip/issues/5624>`_)
- Show a better error message when a configuration option has an invalid value. (`#5644 <https://github.com/pypa/pip/issues/5644>`_)
- Always revalidate cached simple API pages instead of blindly caching them for up to 10
minutes. (`#5670 <https://github.com/pypa/pip/issues/5670>`_)
- Avoid caching self-version-check information when cache is disabled. (`#5679 <https://github.com/pypa/pip/issues/5679>`_)
- Avoid traceback printing on autocomplete after flags in the CLI. (`#5751 <https://github.com/pypa/pip/issues/5751>`_)
- Fix incorrect parsing of egg names if pip needs to guess the package name. (`#5819 <https://github.com/pypa/pip/issues/5819>`_)
Vendored Libraries
------------------
- Upgrade certifi to 2018.8.24
- Upgrade packaging to 18.0
- Add pep517 version 0.2
- Upgrade pytoml to 0.1.19
- Upgrade pkg_resources to 40.4.3 (via setuptools)
Improved Documentation
----------------------
- Fix "Requirements Files" reference in User Guide (`#user_guide_fix_requirements_file_ref <https://github.com/pypa/pip/issues/user_guide_fix_requirements_file_ref>`_)
18.0 (2018-07-22)
=================
......@@ -1207,7 +1254,7 @@ Improved Documentation
- **Dropped support for Python 2.4** The minimum supported Python version is
now Python 2.5.
- Fixed pypi mirror support being broken on some DNS responses. Thanks
- Fixed PyPI mirror support being broken on some DNS responses. Thanks
philwhin. (#605)
- Fixed pip uninstall removing files it didn't install. Thanks pjdelport.
(#355)
......
Metadata-Version: 1.2
Name: pip
Version: 18.0
Version: 18.1
Summary: The PyPA recommended tool for installing Python packages.
Home-page: https://pip.pypa.io/
Author: The pip developers
......@@ -62,6 +62,7 @@ Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pip-installer.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pip-installer.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/pip-installer"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pip-installer"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
[restructuredtext parser]
smart_quotes = no
......@@ -18,10 +18,11 @@ import sys
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
docs_dir = os.path.dirname(os.path.dirname(__file__))
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath(os.pardir))
sys.path.insert(0, docs_dir)
# sys.path.append(os.path.join(os.path.dirname(__file__), '../'))
# -- General configuration ----------------------------------------------------
......@@ -29,7 +30,7 @@ sys.path.insert(0, os.path.abspath(os.pardir))
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# extensions = ['sphinx.ext.autodoc']
extensions = ['sphinx.ext.extlinks', 'docs.pipext', 'sphinx.ext.intersphinx']
extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx']
# intersphinx
intersphinx_cache_limit = 0
......@@ -68,9 +69,8 @@ version = release = 'dev'
# Rather than trying to force RTD to install pip properly, we'll simply
# read the version direct from the __init__.py file. (Yes, this is
# fragile, but it works...)
root = os.path.dirname(os.path.dirname(__file__))
pip_init = os.path.join(root, 'src', 'pip', '__init__.py')
pip_init = os.path.join(docs_dir, '..', 'src', 'pip', '__init__.py')
with open(pip_init) as f:
for line in f:
m = re.match(r'__version__ = "(.*)"', line)
......@@ -102,7 +102,7 @@ today_fmt = '%B %d, %Y'
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_patterns = ['build/', 'man/']
exclude_patterns = ['build/']
# The reST default role (used for this markup: `text`) to use for all documents
# default_role = None
......@@ -127,6 +127,7 @@ pygments_style = 'sphinx'
extlinks = {
'issue': ('https://github.com/pypa/pip/issues/%s', '#'),
'pull': ('https://github.com/pypa/pip/pull/%s', 'PR #'),
'pypi': ('https://pypi.org/project/%s', ''),
}
# -- Options for HTML output --------------------------------------------------
......@@ -252,7 +253,7 @@ latex_documents = [
# List of manual pages generated
man_pages = [
(
'man/pip',
'index',
'pip',
u'package manager for Python packages',
u'pip developers',
......@@ -263,7 +264,7 @@ man_pages = [
# Here, we crawl the entire man/commands/ directory and list every file with
# appropriate name and details
for fname in glob.glob('man/commands/*.rst'):
fname_base = fname[:-4]
fname_base = fname[4:-4]
outname = 'pip-' + fname_base[13:]
description = u'description of {} command'.format(
outname.replace('-', ' ')
......
......@@ -3,4 +3,4 @@
Configuration
=============
This content is now covered in the :ref:`Configuration` section of the :doc:`User Guide <user_guide>`.
This content is now covered in the :ref:`Configuration` section of the :doc:`User Guide </user_guide>`.
===============
Getting Started
===============
We’re pleased that you are interested in working on pip.
This document is meant to get you setup to work on pip and to act as a guide and
reference to the the development setup. If you face any issues during this
process, please `open an issue`_ about it on the issue tracker.
Development tools
=================
pip uses :pypi:`tox` for testing against multiple different Python environments
and ensuring reproducible environments for linting and building documentation.
For developing pip, you need to install ``tox`` on your system. Often, you can
just do ``python -m pip install tox`` to install and use it.
Running Tests
-------------
pip uses the :pypi:`pytest` test framework, :pypi:`mock` and :pypi:`pretend`
for testing. These are automatically installed by tox for running the tests.
To run tests locally, run:
.. code-block:: console
$ tox -e py36
The example above runs tests against Python 3.6. You can also use other
versions like ``py27`` and ``pypy3``.
``tox`` has been configured to any additional arguments it is given to
``pytest``. This enables the use of pytest's `rich CLI`_. As an example, you
can select tests using the various ways that pytest provides:
.. code-block:: console
$ # Using file name
$ tox -e py36 -- tests/functional/test_install.py
$ # Using markers
$ tox -e py36 -- -m unit
$ # Using keywords
$ tox -e py36 -- -k "install and not wheel"
Running pip's test suite requires supported version control tools (subversion,
bazaar, git, and mercurial) to be installed. If you are missing one of the VCS
tools, you can tell pip to skip those tests:
.. code-block:: console
$ tox -e py36 -- -k "not svn"
$ tox -e py36 -- -k "not (svn or git)"
Running Linters
---------------
pip uses :pypi:`flake8` and :pypi:`isort` for linting the codebase. These
ensure that the codebase is in compliance with :pep:`8` and the imports are
consistently ordered and styled.
To use linters locally, run:
.. code-block:: console
$ tox -e lint-py2
$ tox -e lint-py3
The above commands run the linters on Python 2 followed by Python 3.
.. note::
Do not silence errors from flake8 with ``# noqa`` comments or otherwise.
The only exception to this is silencing unused-import errors for imports
related to static type checking as currently `flake8 does not understand
PEP 484 type-comments`_.
Running mypy
------------
pip uses :pypi:`mypy` to run static type analysis, which helps catch certain
kinds of bugs. The codebase uses `PEP 484 type-comments`_ due to compatibility
requirements with Python 2.7.
To run the ``mypy`` type checker, run:
.. code-block:: console
$ tox -e mypy
Building Documentation
----------------------
pip's documentation is built using :pypi:`Sphinx`. The documentation is written
in reStructuredText.
To build it locally, run:
.. code-block:: console
$ tox -e docs
The built documentation can be found in the ``docs/build`` folder.
.. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment
.. _`flake8 does not understand PEP 484 type-comments`: https://gitlab.com/pycqa/flake8/issues/118
.. _`PEP 484 type-comments`: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
.. _`rich CLI`: https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests
Development
===========
pip is a volunteer maintained open source project and we welcome contributions
of all forms. The sections below will help you get started with development,
testing, and documentation.
You can also join ``#pypa`` (general packaging discussion and user support) and
``#pypa-dev`` (discussion about development of packaging tools) `on Freenode`_,
or the `pypa-dev mailing list`_, to ask questions or get involved.
.. toctree::
:maxdepth: 2
getting-started
contributing
release-process
.. note::
pip's development documentation has been rearranged and some older
references might be broken.
.. _`on Freenode`: https://webchat.freenode.net/?channels=%23pypa-dev,pypa
.. _`pypa-dev mailing list`: https://groups.google.com/forum/#!forum/pypa-dev
===============
Release process
===============
Release Cadence
===============
The pip project has a release cadence of releasing whatever is on ``master``
every 3 months. This gives users a predictable pattern for when releases
are going to happen and prevents locking up improvements for fixes for long
periods of time, while still preventing massively fracturing the user base
with version numbers.
Our release months are January, April, July, October. The release date within
that month will be up to the release manager for that release. If there are
no changes, then that release month is skipped and the next release will be
3 month later.
The release manager may, at their discretion, choose whether or not there
will be a pre-release period for a release, and if there is may extend that
period into the next month if needed.
Because releases are made direct from the ``master`` branch, it is essential
that ``master`` is always in a releasable state. It is acceptable to merge
PRs that partially implement a new feature, but only if the partially
implemented version is usable in that state (for example, with reduced
functionality or disabled by default). In the case where a merged PR is found
to need extra work before being released, the release manager always has the
option to back out the partial change prior to a release. The PR can then be
reworked and resubmitted for the next release.
Deprecation Policy
==================
Any change to pip that removes or significantly alters user-visible behavior
that is described in the pip documentation will be deprecated for a minimum of
6 months before the change occurs. Deprecation will take the form of a warning
being issued by pip when the feature is used. Longer deprecation periods, or
deprecation warnings for behavior changes that would not normally be covered by
this policy, are also possible depending on circumstances, but this is at the
discretion of the pip developers.
Note that the documentation is the sole reference for what counts as agreed
behavior. If something isn't explicitly mentioned in the documentation, it can
be changed without warning, or any deprecation period, in a pip release.
However, we are aware that the documentation isn't always complete - PRs that
document existing behavior with the intention of covering that behavior with
the above deprecation process are always acceptable, and will be considered on
their merits.
.. note::
pip has a helper function for making deprecation easier for pip maintainers.
The supporting documentation can be found in the source code of
``pip._internal.utils.deprecation.deprecated``. The function is not a part of
pip's public API.
Release Process
===============
Creating a new release
----------------------
#. Checkout the current pip ``master`` branch.
#. Ensure you have the latest ``wheel``, ``setuptools``, ``twine``, ``invoke``
and ``towncrier`` packages installed.
#. Generate a new ``AUTHORS.txt`` (``invoke generate.authors``) and commit the
results.
#. Bump the version in ``pip/__init__.py`` to the release version and commit
the results. Usually this involves dropping just the ``.devN`` suffix on the
version.
#. Generate a new ``NEWS.rst`` (``invoke generate.news``) and commit the
results.
#. Create a tag at the current commit, of the form ``YY.N``
(``git tag YY.N``).
#. Checkout the tag (``git checkout YY.N``).
#. Create the distribution files (``python setup.py sdist bdist_wheel``).
#. Upload the distribution files to PyPI using twine
(``twine upload dist/*``).
#. Push all of the changes including the tag.
#. Regenerate the ``get-pip.py`` script in the `get-pip repository`_ (as
documented there) and commit the results.
Creating a bug-fix release
--------------------------
Sometimes we need to release a bugfix release of the form ``YY.N.Z+1``. In
order to create one of these the changes should already be merged into the
``master`` branch.
#. Create a new ``release/YY.N.Z+1`` branch off of the ``YY.N`` tag using the
command ``git checkout -b release/YY.N.Z+1 YY.N``.
#. Cherry pick the fixed commits off of the ``master`` branch, fixing any
conflicts and moving any changelog entries from the development version's
changelog section to the ``YY.N.Z+1`` section.
#. Push the ``release/YY.N.Z+1`` branch to github and submit a PR for it against
the ``master`` branch and wait for the tests to run.
#. Once tests run, merge the ``release/YY.N.Z+1`` branch into master, and follow
the above release process starting with step 4.
.. _`get-pip repository`: https://github.com/pypa/get-pip
......@@ -18,5 +18,5 @@ for installing Python packages.
installing
user_guide
reference/index
development
development/index
news
......@@ -6,10 +6,10 @@ Installation
Do I need to install pip?
-------------------------
pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4
downloaded from `python.org <https://www.python.org>`_ or if you are working
in a :ref:`Virtual Environment <pypug:Creating and using Virtual Environments>`
created by :ref:`pypug:virtualenv` or :ref:`pyvenv <pypug:venv>`.
pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4
downloaded from `python.org <https://www.python.org>`_ or if you are working
in a :ref:`Virtual Environment <pypug:Creating and using Virtual Environments>`
created by :ref:`pypug:virtualenv` or :ref:`pyvenv <pypug:venv>`.
Just make sure to :ref:`upgrade pip <Upgrading pip>`.
......@@ -23,8 +23,6 @@ To install pip, securely download `get-pip.py
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
As when running any script downloaded from the web, ensure that you have
reviewed the code and are happy that it works as you expect.
Then run the following::
python get-pip.py
......@@ -36,7 +34,7 @@ Then run the following::
system or another package manager. ``get-pip.py`` does not coordinate with
those tools, and may leave your system in an inconsistent state.
``get-pip.py`` also installs :re