mirror of
https://github.com/pypa/pip
synced 2023-12-13 21:30:23 +01:00
321163fb98
Signed-off-by: Pradyun Gedam <pradyunsg@users.noreply.github.com>
312 lines
12 KiB
ReStructuredText
312 lines
12 KiB
ReStructuredText
.. note::
|
|
|
|
This section of the documentation is currently being written. pip
|
|
developers welcome your help to complete this documentation. If
|
|
you're interested in helping out, please let us know in the
|
|
`tracking issue <https://github.com/pypa/pip/issues/6583>`__, or
|
|
just submit a pull request and mention it in that tracking issue.
|
|
|
|
============
|
|
Issue Triage
|
|
============
|
|
|
|
This serves as an introduction to issue tracking in pip as well as
|
|
how to help triage reported issues.
|
|
|
|
|
|
Issue Tracker
|
|
=============
|
|
|
|
The `pip issue tracker <https://github.com/pypa/pip/issues>`__ is hosted on
|
|
GitHub alongside the project.
|
|
|
|
Currently, the issue tracker is used for bugs, feature requests, and general
|
|
user support.
|
|
|
|
In the pip issue tracker, we make use of labels and milestones to organize and
|
|
track work.
|
|
|
|
Labels
|
|
------
|
|
|
|
Issue labels are used to:
|
|
|
|
#. Categorize issues
|
|
#. Provide status information for contributors and reporters
|
|
#. Help contributors find tasks to work on
|
|
|
|
The current set of labels are divided into several categories identified by
|
|
prefix:
|
|
|
|
**C - Category**
|
|
which area of ``pip`` functionality a feature request or issue is related to
|
|
|
|
**K - Kind**
|
|
|
|
**O - Operating System**
|
|
for issues that are OS-specific
|
|
|
|
**P - Project/Platform**
|
|
related to something external to ``pip``
|
|
|
|
**R - Resolution**
|
|
no more discussion is really needed, an action has been identified and the
|
|
issue is waiting or closed
|
|
|
|
**S - State**
|
|
for some automatic labels and other indicators that work is needed
|
|
|
|
**type**
|
|
the role or flavor of an issue
|
|
|
|
The specific labels falling into each category have a description that can be
|
|
seen on the `Labels <https://github.com/pypa/pip/labels>`__ page.
|
|
|
|
In addition, there are several standalone labels:
|
|
|
|
**good first issue**
|
|
this label marks an issue as beginner-friendly and shows up in banners that
|
|
GitHub displays for first-time visitors to the repository
|
|
|
|
**triage**
|
|
default label given to issues when they are created
|
|
|
|
**trivial**
|
|
special label for pull requests that removes the
|
|
:ref:`news file requirement <choosing-news-entry-type>`
|
|
|
|
**needs rebase or merge**
|
|
this is a special label used by BrownTruck to mark PRs that have merge
|
|
conflicts
|
|
|
|
Automation
|
|
----------
|
|
|
|
There are several helpers to manage issues and pull requests.
|
|
|
|
Issues created on the issue tracker are automatically given the
|
|
``triage`` label by the
|
|
`triage-new-issues <https://github.com/apps/triage-new-issues>`__
|
|
bot. The label is automatically removed when another label is added.
|
|
|
|
When an issue needs feedback from the author we can label it with
|
|
``S: awaiting response``. When the author responds, the
|
|
`no-response <https://github.com/apps/no-response>`__ bot removes the label.
|
|
|
|
After an issue has been closed for 30 days, the
|
|
`lock <https://github.com/apps/lock>`__ bot locks the issue and adds the
|
|
``S: auto-locked`` label. This allows us to avoid monitoring existing closed
|
|
issues, but unfortunately prevents and references to issues from showing up as
|
|
links on the closed issue.
|
|
|
|
|
|
Triage Issues
|
|
=============
|
|
|
|
Users can make issues for a number of reasons:
|
|
|
|
#. Suggestions about pip features that could be added or improved
|
|
#. Problems using pip
|
|
#. Concerns about pip usability
|
|
#. General packaging problems to be solved with pip
|
|
#. Problems installing or using Python packages
|
|
#. Problems managing virtual environments
|
|
#. Problems managing Python installations
|
|
|
|
To triage issues means to identify what kind of issue is happening and
|
|
|
|
* confirm bugs
|
|
* provide support
|
|
* discuss and design around the uses of the tool
|
|
|
|
Specifically, to address an issue:
|
|
|
|
#. Read issue title
|
|
#. Scan issue description
|
|
#. Ask questions
|
|
#. If time is available, try to reproduce
|
|
#. Search for or remember related issues and link to them
|
|
#. Identify an appropriate area of concern (if applicable)
|
|
|
|
Keep in mind that all communication is happening with other people and
|
|
should be done with respect per the
|
|
`Code of Conduct <https://www.pypa.io/en/latest/code-of-conduct/>`__.
|
|
|
|
The lifecycle of an issue (bug or support) generally looks like:
|
|
|
|
#. waiting for triage (marked with label ``triage``)
|
|
#. confirming issue - some discussion with the user, gathering
|
|
details, trying to reproduce the issue (may be marked with a specific
|
|
category, ``S: awaiting-respose``, ``S: discussion-needed``, or
|
|
``S: need-repro``)
|
|
#. confirmed - the issue is pretty consistently reproducible in a
|
|
straightforward way, or a mechanism that could be causing the issue has been
|
|
identified
|
|
#. awaiting fix - the fix is identified and no real discussion on the issue
|
|
is needed, should be marked ``R: awaiting PR``
|
|
#. closed - can be for several reasons
|
|
|
|
* fixed
|
|
* could not be reproduced, no more details could be obtained, and no
|
|
progress can be made
|
|
* actual issue was with another project or related to system
|
|
configuration and pip cannot (or will not) be adapted for it
|
|
|
|
|
|
Requesting information
|
|
----------------------
|
|
|
|
Requesting more information to better understand the context and environment
|
|
that led to the issue. Examples of specific information that may be useful
|
|
depending on the situation:
|
|
|
|
* pip debug: ``pip debug``
|
|
* pip version: ``pip -V``
|
|
* Python version: ``python -VV``
|
|
* Python path: ``python -c 'import sys; print(sys.executable)'``
|
|
* ``python`` on ``PATH``: Unix: ``which python``; Windows: ``where python``
|
|
* Python as resolved by the shell: ``type python``
|
|
* Origin of pip (get-pip.py, OS-level package manager, ensurepip, manual
|
|
installation)
|
|
* Using a virtual environment (with ``--system-site-packages``?)
|
|
* Using a conda environment
|
|
* ``PATH`` environment variable
|
|
* Network situation (e.g. airgapped environment, firewalls)
|
|
* ``--verbose`` output of a failing command
|
|
* (Unix) ``strace`` output from a failing command (be careful not to output
|
|
into the same directory as a package that's being installed, otherwise pip
|
|
will loop forever copying the log file...)
|
|
* (Windows)
|
|
`procmon <https://docs.microsoft.com/en-us/sysinternals/downloads/procmon>`__
|
|
output during a failing command
|
|
(`example request <https://github.com/pypa/pip/issues/6814#issuecomment-516611389>`__)
|
|
* Listing of files relevant to the issue (e.g. ``ls -l venv/lib/pythonX.Y/problem-package.dist-info/``)
|
|
* whether the unexpected behavior ever worked as expected - if so then what
|
|
were the details of the setup (same information as above)
|
|
|
|
|
|
Generally, information is good to request if it can help confirm or rule out
|
|
possible sources of error. We shouldn't request information that does not
|
|
improve our understanding of the situation.
|
|
|
|
|
|
Reproducing issues
|
|
------------------
|
|
|
|
Whenever an issue happens and the cause isn't obvious, it is important
|
|
that we be able to reproduce it independently. This serves several purposes:
|
|
|
|
#. If it is a pip bug, then any fix will need tests - a good reproducer
|
|
is most of the way towards that.
|
|
#. If it is not reproducible using the provided instructions, that helps
|
|
rule out a lot of possible causes.
|
|
#. A clear set of instructions is an easy way to get on the same page as
|
|
someone reporting an issue.
|
|
|
|
The best way to reproduce an issue is with a script.
|
|
|
|
A script can be copied into a file and executed, whereas shell output
|
|
has to be manually copied a line at a time.
|
|
|
|
Scripts to reproduce issues should be:
|
|
|
|
- portable (few/no assumptions about the system, other that it being Unix or Windows as applicable)
|
|
- non-destructive
|
|
- convenient
|
|
- require little/no setup on the part of the runner
|
|
|
|
Examples:
|
|
|
|
- creating and installing multiple wheels with different versions
|
|
(`link <https://github.com/pypa/pip/issues/4331#issuecomment-520156471>`__)
|
|
- using a small web server for authentication errors
|
|
(`link <https://github.com/pypa/pip/issues/2920#issuecomment-508953118>`__)
|
|
- using docker to test system or global configuration-related issues
|
|
(`link <https://github.com/pypa/pip/issues/5533#issuecomment-520159896>`__)
|
|
- using docker to test special filesystem permission/configurations
|
|
(`link <https://github.com/pypa/pip/issues/6364#issuecomment-507074729>`__)
|
|
- using docker for global installation with get-pip
|
|
(`link <https://github.com/pypa/pip/issues/6498#issuecomment-513501112>`__)
|
|
- get-pip on system with no ``/usr/lib64``
|
|
(`link <https://github.com/pypa/pip/issues/5379#issuecomment-515270576>`__)
|
|
- reproducing with ``pip`` from master branch
|
|
(`link <https://github.com/pypa/pip/issues/6707#issue-467770959>`__)
|
|
|
|
|
|
Reaching resolution
|
|
-------------------
|
|
|
|
Some user support questions are more related to system configuration than pip.
|
|
It's important to treat these issues with the same care and attention as
|
|
others, specifically:
|
|
|
|
#. Unless the issue is very old and the user doesn't seem active, wait for
|
|
confirmation before closing the issue
|
|
#. Direct the user to the most appropriate forum for their questions:
|
|
|
|
* For Ubuntu, `askubuntu <https://askubuntu.com/>`__
|
|
* For Other linuxes/unixes, `serverfault <https://serverfault.com/>`__
|
|
* For network connectivity issues,
|
|
`serverfault <https://serverfault.com/>`__
|
|
|
|
#. Just because a user support question is best solved using some other forum
|
|
doesn't mean that we can't make things easier. Try to extract and
|
|
understand from the user query how things could have been made easier for
|
|
them or you, for example with better warning or error messages. If an issue
|
|
does not exist covering that case then create one. If an issue does exist then
|
|
make sure to reference that issue before closing this one.
|
|
#. A user may be having trouble installing a package, where the package
|
|
``setup.py`` or build-backend configuration is non-trivial. In these cases we
|
|
can help to troubleshoot but the best advice is going to be to direct them
|
|
to the support channels for the related projects.
|
|
#. Do not be hasty to assume it is one cause or another. What looks like
|
|
someone else's problem may still be an issue in pip or at least something
|
|
that could be improved.
|
|
#. For general discussion on Python packaging:
|
|
|
|
* `pypa/packaging <https://github.com/pypa/packaging-problems>`__
|
|
* `discuss.python.org/packaging <https://discuss.python.org/c/packaging>`__
|
|
|
|
|
|
Closing issues
|
|
--------------
|
|
|
|
An issue may be considered resolved and closed when:
|
|
|
|
- for each possible improvement or problem represented in the issue
|
|
discussion:
|
|
|
|
- Consensus has been reached on a specific action and the actions
|
|
appear to be external to the project, with no follow up needed
|
|
in the project afterwards.
|
|
|
|
- PEP updates (with a corresponding issue in
|
|
`python/peps <https://github.com/python/peps>`__)
|
|
- already tracked by another issue
|
|
|
|
- A project-specific issue has been identified and the issue no
|
|
longer occurs as of the latest commit on the master branch.
|
|
|
|
- An enhancement or feature request no longer has a proponent and the maintainers
|
|
don't think it's worth keeping open.
|
|
- An issue has been identified as a duplicate, and it is clearly a duplicate (i.e. the
|
|
original report was very good and points directly to the issue)
|
|
- The issue has been fixed, and can be independently validated as no longer being an
|
|
issue. If this is with code then the specific change/PR that led to it should be
|
|
identified and posted for tracking.
|
|
|
|
|
|
Common issues
|
|
=============
|
|
|
|
#. network-related issues - any issue involving retries, address lookup, or
|
|
anything like that are typically network issues.
|
|
#. issues related to having multiple Python versions, or an OS package
|
|
manager-managed pip/python installation (specifically with Debian/Ubuntu).
|
|
These typically present themselves as:
|
|
|
|
#. Not being able to find installed packages
|
|
#. basic libraries not able to be found, fundamental OS components missing
|
|
#. In these situations you will want to make sure that we know how they got
|
|
their Python and pip. Knowing the relevant package manager commands can
|
|
help, e.g. ``dpkg -S``.
|