[New-bugs-announce] [issue13455] Reorganize tracker docs in the devguide

Ezio Melotti report at bugs.python.org
Tue Nov 22 18:55:54 CET 2011

New submission from Ezio Melotti <ezio.melotti at gmail.com>:

The documentation about the bug tracker is sparse in a few different places.  The devguide contains 4 pages:
 1. http://docs.python.org/devguide/helptriage.html
 2. http://docs.python.org/devguide/devrole.html
 3. http://docs.python.org/devguide/triaging.html
 4. http://docs.python.org/devguide/languishing.html

There are two wiki pages:
 5. http://wiki.python.org/moin/SubmittingBugs
 6. http://wiki.python.org/moin/TrackerDocs/

And an additional page in the official docs:
 7. http://docs.python.org/dev/py3k/bugs.html

Some content is duplicated, 5 and 7 are similar, and 6 has the same content of 3 and 2.

The idea is to have 2 pages about the tracker in the devguide:
 * A new "tracker.rst" page that includes all the information about the tracker except the description of the fields;
 * The old "triaging.rst", that only describes the meaning of the fields.

The attached patch groups this information in the new page, removing the old pages (1, 2, 4) and updating the index and toc.

The content of the wiki pages (5 and 6) should be deleted and a pointer to the devguide should be added instead.
The bugs page in the docs (7) should not contain all the steps necessary to register and open an issue IMHO, but just a short description and a link to the devguide.

Currently the structure of the new page is:
  +-- Using the Issue Tracker
  |     +-- Checking if a bug already exists
  |     +-- Reporting an issue
  +-- Helping Triage Issues
  |     +-- Classifying Reports
  |     +-- Reviewing Patches
  |     +-- Finding an Issue You Can Help With
  |     +-- Gaining the "Developer" Role on the Issue Tracker
  +-- The Meta Tracker

I mostly copy/pasted from other pages (e.g. "Using the Issue Tracker" is copied from 7), so this should be reorganized a bit.
The things I would like to include here are:
 * how to search issues
 * how to report a new issue
 * how to classify issues
 * how to make reviews
 * how to find interesting issues
 * how to get the developer role
 * how to use the keyboard shortcuts

It might be better to just list all these things, or group them in "basic" (searching/reporting) and "advanced" (everything else), or keep a step by step "how to report a bug" separate and just describe specific tasks here (like "how to register/login/report").

assignee: ezio.melotti
components: Devguide
files: issue13455.diff
keywords: patch
messages: 148131
nosy: brett.cannon, eli.bendersky, eric.araujo, ezio.melotti, ncoghlan, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Reorganize tracker docs in the devguide
Added file: http://bugs.python.org/file23757/issue13455.diff

Python tracker <report at bugs.python.org>

More information about the New-bugs-announce mailing list