Opened 13 years ago

Closed 13 years ago

#15796 closed Bug (fixed)

Contributing docs need to be updated to include new triage stages and ticket states

Reported by: Russell Keith-Magee Owned by: Julien Phalip
Component: Documentation Version: 1.2
Severity: Release blocker Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Julien Phalip)

Recent changes to Trac add a type and severity option, and a Needs Info triage state, However, these are currently undocumented.

Marking this as a release blocker because it's a documentation flaw in our main contribution process.

Attachments (2)

15796.contributing-doc-refactor.diff (158.9 KB ) - added by Julien Phalip 13 years ago.
15796.contributing-doc-refactor.2.diff (159.0 KB ) - added by Julien Phalip 13 years ago.

Download all attachments as: .zip

Change History (12)

comment:1 by Julien Phalip, 13 years ago

Description: modified (diff)

I see that the "needsinfo" resolution is already documented here: http://docs.djangoproject.com/en/dev/internals/contributing/

This makes me realise that there's a lot of overlap between http://docs.djangoproject.com/en/dev/internals/contributing/ and http://docs.djangoproject.com/en/dev/howto/contribute/
The former is also very dense as it contains tons of loosely related info like reporting bugs, code style, committing patches, branch policies, etc.

The Trac report (http://code.djangoproject.com/wiki/Reports) is also very useful and would, I think, deserve to be fleshed out more and then be integrated in the official Django doc itself to provide concrete examples and hints on how to contribute code.

I'm not sure how to do it yet, but it feels that we should perhaps rearrange everything into a more logical structure and with less duplicate information. Do you agree in principle? If so then I'm keen to have a go at it.

This ticket only asks for the few small doc fixes but I'm just wondering if we should maybe go for a bigger change while we're at it. Or maybe it's best to take this over to a separate ticket. Let me know what you think. Thanks!

comment:2 by Julien Phalip, 13 years ago

Just to be a bit clearer about my proposal: Keep the (awesome) code contributing howto guide (http://docs.djangoproject.com/en/dev/howto/contribute/) and update it with the recent Trac changes. Then remove all the triaging info from http://docs.djangoproject.com/en/dev/internals/contributing/ and merge the relevant parts into the howto guide. And then restructure http://docs.djangoproject.com/en/dev/internals/contributing/ and then potentially split it in multiple standalone sections (like the current howto guide is).

comment:3 by Julien Phalip, 13 years ago

Easy pickings: unset
Owner: changed from nobody to Julien Phalip

After discussing with Russell I'll take a stab at rejigging the contribution doc as enunciated above. Wish me luck :-)

by Julien Phalip, 13 years ago

comment:4 by Julien Phalip, 13 years ago

Has patch: set

This was a big patch so I took it to the dev-list for feedback: http://groups.google.com/group/django-developers/browse_thread/thread/15441f05a72063fd

comment:5 by Jannis Leidel, 13 years ago

It's not correct anymore to point to Jacob to add a blog to the community section since the community-redux refactor landed. You can simply add your feed yourself.

comment:6 by Jannis Leidel, 13 years ago

Triage Stage: AcceptedReady for checkin

Content wise it's great stuff, marking it as RFC.

comment:7 by Julien Phalip, 13 years ago

Thanks Jannis, well spotted! Let me just quickly fix that as well as a couple of small things that were suggested on the dev-list. Will post a new patch shortly.

by Julien Phalip, 13 years ago

comment:8 by Julien Phalip, 13 years ago

OK, I've made those little fixes. By the way, you can browse the html output here: http://dl.dropbox.com/u/3364022/djangodoc/internals/contributing/index.html

Thank you!

comment:9 by Jannis Leidel, 13 years ago

LGTM.

comment:10 by Jannis Leidel, 13 years ago

Resolution: fixed
Status: newclosed

In [16284]:

Fixed #15796 -- Restructured the contributing documentation and added note about newly added Trac abilities. Many thanks to Julien Phalip.

Note: See TracTickets for help on using tickets.
Back to Top