JIRA Label convention Edited

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?
  • 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

3 comments

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.

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

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 - thankyou so much, thats exacty what I wanted and stupidly easy as well. Cheers.

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.

@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.

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.

Comment

Log in or Sign up to comment
Atlassian Community Anniversary

Happy Anniversary, Atlassian Community!

This community is celebrating its one-year anniversary and Atlassian co-founder Mike Cannon-Brookes has all the feels.

Read more
Community showcase
Julia Dillon
Posted Apr 17, 2018 in Jira

Tell us how your team runs on Jira!

Hey Atlassian Community! Today we are launching a bunch of customer stories about the amazing work teams, like Dropbox and Twilio, are doing with Jira. You can check out the stories here. The thi...

809 views 2 19
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you