From a8996f25e558de130d43df0b7df59074afadc24b Mon Sep 17 00:00:00 2001 From: Chris Hunt Date: Tue, 13 Aug 2019 01:43:04 -0400 Subject: [PATCH 1/2] Initial triage guide. --- docs/html/development/issue-triage.rst | 286 +++++++++++++++++++++++++ 1 file changed, 286 insertions(+) diff --git a/docs/html/development/issue-triage.rst b/docs/html/development/issue-triage.rst index 621b9e6a4..61378ec8b 100644 --- a/docs/html/development/issue-triage.rst +++ b/docs/html/development/issue-triage.rst @@ -23,3 +23,289 @@ 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 `__ 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 that when used on a PR removes the news file requirement + +**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 `__ +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 `__ bot removes the label. + +After an issue has been closed for 30 days, the +`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 `__. + +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 that pip cannot improve its behavior in the context + of + + +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 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 `__ + output during a failing command + (`example request `__) +* 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 `__) +- using a small web server for authentication errors + (`link `__) +- using docker to test system or global configuration-related issues + (`link `__) +- using docker to test special filesystem permission/configurations + (`link `__) +- using docker for global installation with get-pip + (`link `__) +- get-pip on system with no ``/usr/lib64`` + (`link `__) +- reproducing with ``pip`` from master branch + (`link `__) + + +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 `__ + * For Other linuxes/unixes, `serverfault `__ + * For network connectivity issues, + `serverfault `__ + +#. 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 `__ + * `discuss.python.org/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 `__) + - 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``. From 2a4cfcb0215785b5534f1790f9404a75033394b5 Mon Sep 17 00:00:00 2001 From: Chris Hunt Date: Sat, 7 Sep 2019 10:20:34 -0400 Subject: [PATCH 2/2] Address review comments. --- docs/html/development/contributing.rst | 2 ++ docs/html/development/issue-triage.rst | 7 ++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/html/development/contributing.rst b/docs/html/development/contributing.rst index 32b0ca864..75108f515 100644 --- a/docs/html/development/contributing.rst +++ b/docs/html/development/contributing.rst @@ -89,6 +89,8 @@ from a description of the feature/change in one or more paragraphs, each wrapped at 80 characters. Remember that a news entry is meant for end users and should only contain details relevant to an end user. +.. _`choosing-news-entry-type`: + Choosing the type of NEWS entry ------------------------------- diff --git a/docs/html/development/issue-triage.rst b/docs/html/development/issue-triage.rst index 61378ec8b..cf125ccdb 100644 --- a/docs/html/development/issue-triage.rst +++ b/docs/html/development/issue-triage.rst @@ -71,7 +71,8 @@ In addition, there are several standalone labels: default label given to issues when they are created **trivial** - special label that when used on a PR removes the news file requirement + special label for pull requests that removes the + :ref:`news file requirement ` **needs rebase or merge** this is a special label used by BrownTruck to mark PRs that have merge @@ -149,8 +150,7 @@ The lifecycle of an issue (bug or support) generally looks like: * 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 that pip cannot improve its behavior in the context - of + configuration and pip cannot (or will not) be adapted for it Requesting information @@ -160,6 +160,7 @@ 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)'``