JIRA Label convention

[Satish Swargam]

Are there any naming conventions for JIRA labels?  Trying to find a way to standardize on label usage.

JIRA labels observe the following conventions:

• Case-sensitive: Labels are case-sensitive. Be consistent in the use of upper- and lower-case characters when adding labels to multiple tickets. For example, JIRA creates separate labels for the entries Catalog and catalog.
• Spelling: Spelling differences in labels affect search results in JIRA; for example, JIRA distinguishes pre-requisite and prerequisite as unique terms. A search on pre-requisite may retrieve different tickets than a search on prerequisite. 
  
• Single word: JIRA supports only single-word labels. If you must use more than one word in a label, create a compound word using a hyphen; for example, QA-plan or shoot-sheet. 
  For additional details about label conventions, see your project manager or supervisor. 
  
• JIRA labels are shared across JIRA projects.

Suggested JIRA label conventions:

• The labels should be unique and not conflict with other reporting.
• The labels should be short and not too wordy. The labels should aid in filtering issues effectively and multiple labels are acceptable.
  • Not preferred:
    • performance-scalability-reliability-and-regulatory-report
    • performance-and-scalability-report
    • performance-scalability-reliability-and-not-regulatory-report
  • Preferred:
    • performance
    • scalability
    • reliability
    • regulatory
    • report
• Use abbreviations for lengthy labels. A label should be at least 3 characters in length.
  • e.g., NFR (Non Functional Requirement)
• Use Pascal case, Hungarian notation, compounds, hyphenated compounds or snake case to separate words?
  • FunctionalRequirement (Pascal case)
  • functionalRequirement (Hungarian notation)
  • functionalrequirement (compounds)
  • functional-requirement (hyphenated compounds)
  • functional_requirement (Snake case)
• Avoid repetitions of the same word across labels
  • Not preferred:
    • NFR-source-ISO/IEC-25010
    • NFR-source-ISO/IEC-9126-1:2001
  • Preferred:
    • NFR
    • ISO/IEC-25010 | ISO/IEC-9126-1:2001

[Nic Brough -Adaptavist-]

Personally, I would simplify it further, as it's very clear that people trying to be clever with labels and tags wastes a lot of time and makes them wonderfully useful (this is not just an Atlassian thing)

Your statement "The labels should be short and not too wordy." really does ring true, and to do that, I would keep them *very* simple.  Lower case, alphanumeric or a hyphen (for separators), and of a restricted length.

To help users out, I'd want a system that

• Suggests similar labels to what they're typing
• Two layers - one predefined by administrators as "good" and then free-range on the rest
• A spelling check to suggest better words (not enforce, just suggest)
• Search should ignore hyphens

This is based on seeing a lot of systems using labels that are functionally useless because people use sentences, capitalisation and separators to try to make their labels unique or memorable, which defeats the whole purpose of them.

[Satish Swargam]

Thanks, @Nic Brough -Adaptavist-.

Lower case, alphanumeric or a hyphen (for separators), and of a restricted length.

The popular convention seems to be lower case with hyphenated compounds and snake case.

To help users out, I'd want a system that

• Suggests similar labels to what they're typing

  This is currently supported. Labels that have '/' or ':' do not show up as sugggestions. '-' and '_' are included in the suggestions.

• Two layers - one predefined by administrators as "good" and then free-range on the rest

  This one is interesting. Could be an enhancement request in a later version of JIRA. Should it be color coded in the suggestions autocomplete renderer?

• A spelling check to suggest better words (not enforce, just suggest)

  I wonder how this will work with the suggestions autocomplete renderer as the current function is based on existing labels.

Ref: JIRA v7.2.x

[Adrian Pottier]

Hi - One frustration im finding is that Labels only return items that are in the same space - I work across 2 different Confluence spaces and use the same label for pages in BOTH spaces - but when i click a label in Space A, only pages in that space are shown on the list.

Is there any Cross-Space labelling that anyone knows about?

How can I return pages from >1 space with the same label? Many thanks as always! Adrian

[Boris Berenberg - Atlas Authority]

https://confluence.atlassian.com/doc/content-by-label-macro-145566.html

https://marketplace.atlassian.com/plugins/net.customware.confluence.plugin.reporting/server/overview

But this question was more focused on JIRA I believe.

[Adrian Pottier]

Boris - thankyou so much, thats exacty what I wanted and stupidly easy as well. Cheers.

[Boris Berenberg - Atlas Authority]

I actually take a slightly different approach to this. I don't give people best practices because labels are not intuitive. There are a million other things that I would rather educate them on instead like how to write their own JQL.

My approach is twofold:

1. Remove labels from as many screens as possible
2. Work with teams to understand their use cases and replace with custom fields that provide structure to the data

Whatever usage of labels I end up with is fairly small and not worth the effort to try and manage.

[Satish Swargam]

@Boris Berenberg - Atlas Authority,

Custom fields should be used where applicable. This however requires JIRA privileges.

Labels are free range and educating Jira users on effective JQL with labels will certainly help. This includes good choices for labels.

The usage of labels depends on the number of users, number of issues, number of JIRA projects and its related management. I see an increase in its usage as it does not need additional privileges.

Striking the right balance between free range and governance could be key.

[Cash Coyne]

We have 20K users on our JIRA instance and when I start typeing in the Labels field, ALL those labels appear.  So, to simplify things we DID have to use repetitions with our labels.

We prefixed each label with something that was unique amongst all the labels in our JIRA installation.  For example "SX_"  then all the labels for our team began with "SX_".  Then we went further into categories, so for example all labels relating to a region where prefixed with "SX_RGN_" ie: SX_RGN_Asia, SX_RGN_England... or a business line category was "SX_BL_" allowing labels like SX_BL_Equity, SX_BL_Debt.  So when a user started typing a label and they entered the SX_ followed by the CAT_, they saw all the options available.

Why did we do this?

1. We can't have custom fields in our instance
2. It prevented confusion with other teams labels and potentially choosing something like "equity" instead of "Equity".
3. It kind of simulated a drop-box selection field and made it easier on our team to use the labels.

Just a tip for anyone that finds themselves in an environment like ours.

[Brandon]

I am actually planning to update my existing labels to be like those you described. I'm curious if this has been effective for you? Have you encountered any issues? Anything you wish you knew ahead of time? 

[Justin Sher]

>"Single word: JIRA supports only single-word labels."

Okay, I have come across an unusual case where this is not the case.

I was needing to add to individual JIRA tickets and did this via a copy/paste from another document, rather than typing them in (there were a lot)

These are the methods:

1. If I type my labels in which are separated by a space, they will become individual labels codes. eg. typing "Item1 Item2 Item3" will become "Item1" "Item2" "Item3".
2. However, if I copy and paste from another document the phrase "Item1 Item2 Item3", it may prompt me to add a "New Label?" and if I select this, then the whole phrase is added as a label including the spaces.
3. Carrying on from point 2, if I do not click on the "New Label?" prompted, but click the tick (or outside the field), only then will the labels be added as "Item1" "Item2" "Item3".

So, yes, you can add a label with spaces!

A bug? You decide...

[Nic Brough -Adaptavist-]

I really wish they'd undo that change and ban spaces in labels.  Have a look at the community labels here - we had 20,000 of them when we started, with around 10,000 of them being utterly useless because of spaces.