[issue13455] Reorganize tracker docs in the devguide
Ezio Melotti ezio.melo...@gmail.com added the comment: The attached patch has been committed in 252e2aabc87a, and the wiki pages have been updated to link to the devguide. -- resolution: - fixed stage: patch review - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Changes by Eli Bendersky eli...@gmail.com: -- nosy: -eli.bendersky ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Changes by Ezio Melotti ezio.melo...@gmail.com: -- stage: needs patch - patch review type: - enhancement ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Terry J. Reedy tjre...@udel.edu added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Nick Coghlan ncogh...@gmail.com added the comment: 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) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Éric Araujo mer...@netwok.org added the comment: [...] 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Éric Araujo mer...@netwok.org added the comment: +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 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Ezio Melotti ezio.melo...@gmail.com added the comment: 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 tracker[0], I moved the discussion here to get more people involved before making changes. [0]: http://psf.upfronthosting.co.za/roundup/meta/issue119 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Antoine Pitrou pit...@free.fr added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Ezio Melotti ezio.melo...@gmail.com added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
New submission from Ezio Melotti ezio.melo...@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: 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). -- 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 rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Antoine Pitrou pit...@free.fr added the comment: 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. -- nosy: +pitrou ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Petri Lehtinen pe...@digip.org added the comment: 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. -- nosy: +petri.lehtinen ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13455] Reorganize tracker docs in the devguide
Nick Coghlan ncogh...@gmail.com added the comment: 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). -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13455 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
