Reorganize tracker docs in the devguide

[ezio-melotti]

BPO	13455
Nosy	@brettcannon, @terryjreedy, @ncoghlan, @pitrou, @ezio-melotti, @merwok, @akheron
Files	issue13455.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2012-06-17.11:27:14.544>
created_at = <Date 2011-11-22.17:55:53.875>
labels = ['type-feature', 'docs']
title = 'Reorganize tracker docs in the devguide'
updated_at = <Date 2012-06-17.11:27:14.506>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2012-06-17.11:27:14.506>
actor = 'ezio.melotti'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2012-06-17.11:27:14.544>
closer = 'ezio.melotti'
components = ['Devguide']
creation = <Date 2011-11-22.17:55:53.875>
creator = 'ezio.melotti'
dependencies = []
files = ['23757']
hgrepos = []
issue_num = 13455
keywords = ['patch']
message_count = 12.0
messages = ['148131', '148137', '148138', '148160', '148193', '148211', '148216', '148221', '148273', '148694', '152028', '163055']
nosy_count = 7.0
nosy_names = ['brett.cannon', 'terry.reedy', 'ncoghlan', 'pitrou', 'ezio.melotti', 'eric.araujo', 'petri.lehtinen']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13455'
versions = []

[ezio-melotti]

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:
tracker.rst
+-- 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").

[pitrou]

I think the reason these docs are scattered is that the devguide is a guide, not a reference manual. I don't think this patch makes sense: if the tracker really needed so much text to explain how it works, then the tracker would have a severe UI problem. Most people use bug trackers without ever reading a manual first.

[akheron]

It seems to me there's not that much text on how the tracker itself works. Only sections "Checking if a bug already exists" and "Reporting an issue" have this kind of information. The text in these sections seems to be mostly from http://docs.python.org/bugs.html, so it's not new content.

Other sections mostly deal with the way the tracker is used or should be used for the development of CPython.

I like the idea of this patch. As Antoine said, people usually know how to use web applications nowadays, so moving the info from http://docs.python.org/bugs.html to devguide (replacing it with a shorter description) sounds good.

[ncoghlan]

Documenting the tracker UI itself isn't the big issue - what is useful (and what I think Ezio is getting at) is having a single place where newcomers can get a better idea of how we *use* the tracker.

If someone just wants to report a bug, then sure, they shouldn't need to read the dev guide (so I disagree with the idea of making any significant changes to the bugs page in the docs), but making it easier for newcomers to learn the ropes is the main reason we have a devguide at all, so I'm definitely +1 on the general idea.

It would also give us a place to document the auto-linkification rules (similar to what was done recently for the post-commit hooks).

[merwok]

+1 on grouping existing info into one or two files in the devguide
+1 to removing the wiki pages
+1 on keeping some basic directions in the main docs

[ezio-melotti]

I think the reason these docs are scattered is that the devguide is a
guide, not a reference manual. I don't think this patch makes sense: if
the tracker really needed so much text to explain how it works, then
the tracker would have a severe UI problem. Most people use bug
trackers without ever reading a manual first.

This is true, however different people can figure out a different amount of things just by using and experiment with something. While most of the tasks should be obvious, some are a bit more advanced, and even the "obvious" once might not be obvious for everyone. So IMHO writing down a few sentences doesn't hurt.
Also the lines between developer, contributor, and user that reports an issue are not so well defined, so it might be ok to add information that are not aimed just to core-developers in the devguide.

If someone just wants to report a bug, then sure, they shouldn't need
to read the dev guide

I also don't expect them to follow the bugs page in the doc step by step. I think they can figure out most of the steps on their own -- but if they get stuck with a specific step (e.g. registration), they should be able to find more information about it easily. Having all the doc in the same place and a short section for each possible step would solve this, and it's IMHO better than a descriptive section of the whole process. Similarly this applies for the description of the fields (that's why I used a list and highlighted with bold text the fields' names).

(so I disagree with the idea of making any significant changes
to the bugs page in the docs)

I was planning to replace it with a paragraph that says that something like "If you think you found an issue, you can search the bug tracker at <bugs.python.org> to see if the issue is known. If it's not, you can register to the issue tracker and report it. For more information see the <devguide>. It is not possible to submit anonymous reports."

It would also give us a place to document the auto-linkification
rules (similar to what was done recently for the post-commit hooks).

This is already documented in the "triaging" page, in the section about the "Comment" field.

This issue was initially reported on the meta tracker0, I moved the discussion here to get more people involved before making changes.

[pitrou]

This is true, however different people can figure out a different
amount of things just by using and experiment with something. While
most of the tasks should be obvious, some are a bit more advanced, and
even the "obvious" once might not be obvious for everyone. So IMHO
writing down a few sentences doesn't hurt.

Well, it does hurt, because the more sentences you write, the more the
devguide becomes bloated and difficult to follow (especially for
non-native English speakers who might not read English very fast). The
devguide is *already* too big.

The devguide was supposed to be something that you read quickly and
easily, not an exhaustive reference of how development works. Or at
least there should be a clear separation between the two (the guide
part, and the reference part). The guide part being the most important,
while the reference is really optional.

And, really, if you want people to feel more comfortable with the
tracker, it would be more productive to improve the tracker itself. No
amount of documentation will make a UI usable.

Also the lines between developer, contributor, and user that reports
an issue are not so well defined, so it might be ok to add information
that are not aimed just to core-developers in the devguide.

The devguide is *not* primarily for core developers. It's for new
contributors who want to get set up, so that they don't give up in the
absence of clear indications. Being useful for core developers is a nice
extra, but it was not the original intent.

[ezio-melotti]

Well, it does hurt, because the more sentences you write, the more the
devguide becomes bloated and difficult to follow

OTOH is easy to ignore an "how to register to the tracker" section if you are already registered or if you don't need to register now or you think you know how to do it.
Also note that I'm not adding these sections, but I'm just moving them from the bugs page in the doc (with some markup changes and refactoring).
The only section I added is "Finding an Issue You Can Help With".

The devguide is *not* primarily for core developers. It's for new
contributors who want to get set up, so that they don't give up in the
absence of clear indications.

Agreed, and registering and using the bug tracker is part of this set up, regardless of how obvious the process is (or should be).

Anyway, it would be fine with me to not document these "basic" tasks (how to register/login/search), but it seems to me that people think that the content of the bugs page is useful, and I would rather have it with the rest in the devguide, rather than having it in a separate page.

[merwok]

[...] The devguide is *already* too big. [...]
The devguide was supposed to be something that you read quickly and easily, not an exhaustive
reference of how development works. Or at least there should be a clear separation between the
two (the guide part, and the reference part). [...]
The devguide is *not* primarily for core developers. It's for new contributors who want to get
set up, so that they don't give up in the absence of clear indications. [...]

Thanks Antoine, I was not aware of that or I had forgotten it. The old python.org/dev pages contained information for new and experienced core devs too, so I thought the devguide was intended to contain the same info. I’ll support a clearer separation between the guide and the reference, to make the devguide less overwhelming for new contributors but still complete for core devs.

[ncoghlan]

Something else such docs could cover is how to manage remote Hg repos such that the "Create Patch" button does the right thing.

Basically, you need to make sure an appropriate CPython version is found in the ancestors of the tip your working branch. This is most easily achieved either by working directly on the default branch in your remote repo, or else by merging directly from default to your feature branch (i.e. not via another feature branch).

If you don't follow this rule, the generated patch will occasionally incorrectly revert changes in CPython that you didn't intend to affect.

(see http://psf.upfronthosting.co.za/roundup/meta/issue428 for some background)

[terryjreedy]

Antoine, what reference other than the devguide are you referring to?
If you keep info I need out of the devguide, where am I supposed to find it? python.org/dev now redirects to python.org/devguide.

[ezio-melotti]

The attached patch has been committed in 252e2aabc87a, and the wiki pages have been updated to link to the devguide.