Write a handbook page about how issue tags are intended to be used

+1 on this - it's very hard to understand how the tags are supposed to be used

First step would be having a handbook page to link to. ;) Once that exists, adding a link to it to the issue form is trivial...

In my experience, here are (some of) the helpful things I've used issue tags for:

1. Initiatives that span multiple projects that you want to track all together. E.g. git phase 2 or drupal.org redesign.
2. Initiatives within a single project that span multiple components. E.g. core's usability issue queue.
3. Classifying issues with more detail than the status, especially defining what exactly "needs work". E.g. needs tests or needs documentation.
4. Tracking "milestones", e.g. the Project module's 6.x-1.0 blocker issue queue or issues targeted for implementation during git sprint 4.
5. Classifying issues by other criteria than the hard-coded default fields. For example:
   • Defining how difficult certain issues are expected to be, e.g. novice issues.
   • Tracking (and at times debating) if an issue qualifies as an API change, if it
     breaks the string freeze, etc.

   You could argue that some of these are just other cases of the "stuff that spans multiple components" rule above, but I think of these more as properties of the issue itself (novice, breaks string freeze, not an API change) as opposed to an actual initiative like improving usability. Doesn't really matter, that's the nice thing about arbitrary tagging -- you don't have to pre-define the "schema" for how it's going to be used.

I'm sure folks could come up with others, but those are some of the highlights for me.

Pointless things that should be avoided:

- Duplicating any of the hard-coded issue fields (component, assigned, priority, status, etc).
- Random keywords

Cheers,
-Derek

joachim, i haven't noticed this - unless you're referring to my going through a couple months ago and trying to tag as many issues as possible (but i wouldn't consider myself a newb, or the tags useless).

jennifer and i have been trying to categorize issues so that it's easier to delegate work (and we also used a tag for some of the initiatives that came out of our meeting in december, mostly docs infra issues). so mostly in the #5 grain (from dww's comment above).

consistent tags we've been using, off the top of my head:

- initiatives: docsyvr2010, d7docs

- general classifying: theming, developer, server stuff, distributions (and there are a few that were for far fewer issues than those)

we intend to post the commonly used tags somewhere to help with this, but are very busy with the d7 launch hot on our heels. if you want to start a page about this, that would be very helpful, you can link to the tags above in it.

ps. - sorry i just realized the history of this issue was on the d.o queue and not docs - did you mean in the docs queue specifically? maybe i am misundertanding altogether.

Slightly OT, but at one point I had issue tags in their own collapsed fieldset by default, to "hide" them from novice users. At some point, someone undid that and now they're really prominent right above the "Save" button, very visible. I don't remember seeing an issue for that, but I assumed someone did it on purpose to make it easier for advanced issue queue users to manipulate tags without the extra click. I still think it'd be better if they were more hidden, since it'd be less inviting for people who don't know what they are to feel like they have to fill them out.

No, this has nothing to do with tags used in the docs queue. This is just a general problem of novice issue queue users adding all sorts of pointless tags.

ahh... gotcha. hmm - this seems like a slightly ominous thing to document, since every maintainer probably has a bit of a system of their own... but i can see how some standard practices would help.

going to try and get some more opinions here...

Ooh yes, tagging of issues should be clarified. At least provide a baseline of what is appropriate, even though as ariane says, there are going to be different "rules" for each project though. And my other pet peeve is duplication of tags because of slight variations in spelling or formatting.

For anyone with access to the issue taxonomy, the terms are pretty bonkers, e.g. ' caracter
http://drupal.org/admin/content/taxonomy/9

Couple potential guidelines:
* Don't introduce a new tag unless you are the project maintainer or have been asked to
* Check your spelling and formatting carefully to ensure you're not inadvertantly creating a new tag.

The other ones proposed above sound good too.

anyone able to amalgamate the suggestions into dww's list, and perhaps break it into a "maintainers guidelines" and "general guidelines" or something of the sort, that we can finalize and post?

Taxonomy edit link: http://drupal.org/admin/content/taxonomy/edit/vocabulary/9

We can probably rename the vocabulary that indicates it's for maintainers.

Below is an amalgamation - somewhat repetitive.

The "Issue tags" feature available when creating or comment on issues is for project maintainers to classify or group related issue. Users should not use issue tags for general tagging of issues.

General guidelines

Don't use random words or hard-coded issue fields (component, assigned, priority, status, etc).

Don't introduce a new tag unless you are the project maintainer or have been asked to.

Check your spelling and formatting carefully to ensure you're not inadvertantly creating a new tag.

Project maintainer guidelines

You can use tags for...

• Initiatives that span multiple projects that you want to track all together. E.g. git phase 2 or drupal.org redesign.
• Initiatives within a single project that span multiple components. E.g. core's usability issue queue.
• Classifying issues with more detail than the status, especially defining what exactly "needs work". E.g. needs tests or needs documentation.
• Tracking "milestones", e.g. the Project module's 6.x-1.0 blocker issue queue or issues targeted for implementation during git sprint 4.
• Classifying issues by other criteria than the hard-coded default fields. For example:
  • Defining how difficult certain issues are expected to be, e.g. novice issues.
  • Tracking (and at times debating) if an issue qualifies as an API change, if it
    breaks the string freeze, etc.

@silverwing, that looks like a great start - i think we could move that into a docs page and then update it further if needed in the future. moving to needs review, anyone else have reviews, or shall we wrap this one up?

Page Created - http://drupal.org/node/1023102

Great. I just submitted #1023108: Make issue tags less visible by default and link to the documentation on how to use them. Therefore, this issue here is fixed.

fantastic! thanks all!

Seems to be a missing end of a link on http://drupal.org/node/1023102 around "E.g. needs test"

@voxpelli: Thanks for the pointer. Always feel free to just edit documentation pages directly to fix broken links like that. Anyway, took care of it myself in this case.

Found 2 other issue tag related pages that may need to be addressed.

"Issue submission form fields" http://drupal.org/node/314328 - unless we want to use the tags mentioned, that section should be replaced with a link to the new page.

"Documentation issue reports" http://drupal.org/node/24565 - I can't recall users adding those tags listed, but let the doc admins decide what to do with it.

ooh good catch - i'm wondering if we shouldn't move the new content on http://drupal.org/node/1023102 to the tag section on http://drupal.org/node/314328 though it will be more buried there. otherwise, yes, we should remove that content and point to the new page (don't want duplicate info to keep synced)

i'd really like to totally replace the list of tags on http://drupal.org/node/24565 with ones we actually use:

- theming
- server stuff
- distributions
- docs admins (this would cover all the tags suggested in the list right now)
- developer
- d7docs
- git phase 2
- git development
- docsyvr2010

It looks like someone could just take @silverwing's ideas in #13 above, past it into a handbook page, add some other ideas that were discussed in the issue queue and close this issue.

What am I missing? How has this sat here as an open issue for 3 years?

The handbooks are fairly open. Shouldn't be a big deal to add this somewhere

This has been fixed for a while

Thanks Lee!