Skip to content

Issue labelling

Jump to bottom
David Langley edited this page Feb 1, 2024 · 12 revisions

You can find the full list of project labels here for web/desktop, Android and iOS.

We strive to completely cover all applicable issues with these core labels:

  1. Type — Every issue is assigned a type:

    • T-Defect: Bugs, crashes, hangs, vulnerabilities, or other reported problems (web/desktop, Android and iOS)
    • T-Enhancement: New features, changes in functionality, performance boosts, user-facing improvements (web/desktop)
    • T-Task: Refactoring, enabling or disabling functionality, other engineering tasks (web/desktop)
    • T-Other: Questions, user support, anything else (web/desktop)

  2. Severity — Only issues labelled T-Defect are also assigned a severity, examples are provided for these (based off usability standards):

    • S-Critical: Prevents work, causes data loss and/or has no workaround (web/desktop)
      • Example:
        • Users cannot fulfil a simple task
    • S-Major: Severely degrades major functionality or experience of the product, with no satisfactory workaround (web/desktop)
      • Examples:
        • Users aren’t in control and feel stuck (no emergency exits)
        • UI is not accessible (guidelines)
        • Users aren’t in control and feel stuck (no emergency exits)
        • Error prevention does not exist
    • S-Minor: Impairs non-critical functionality or suitable workarounds exist (web/desktop)
      • Examples:
        • No visual consistency or symmetry
        • Information is not structured to fulfil users’ primary goals
        • Lack of visual feedback on system status (i.e: loading status)
        • Language is not clear or inconsistent
        • Cognitive load is heavy
    • S-Tolerable: Low/no impact on users (web/desktop)
      • Examples:
        • Lack of Flexibility (personalisation, shortcuts and customisation)
        • Help & documentation is not easily accessible

  3. Occurrence — All issues labelled T-Defect are also assigned a prevalence:

    • O-Frequent: Affects or can be seen by most users regularly or impacts most users' first experience (web/desktop)
    • O-Occasional: Affects or can be seen by some users regularly or most users rarely (web/desktop)
    • O-Uncommon: Most users are unlikely to come across this or unexpected workflow (web/desktop)

    This label may also be used for other types of issues.

  4. Area — Most issues are assigned one or several "areas" using one of the many A- prefixed labels, e.g. A-Composer or A-Spaces. Each area label maps to a group of features or portion of the UI surface in the app. All A-* labels should have a description and the colour should be #bfd4f2 unless it's a team label.

Other common labels

We have a handful of other labels which are added on an as-needed basis, and not expected to be exhaustive:

  • Exceptions — Special flags for issues and pull requests:

    • X-Needs-Info: This issue is blocked pending further information from the reporter (web/desktop)
    • X-Regression: Denotes things breaking which previously worked (web/desktop)
    • X-Release-Blocker: Issues which must be resolved before making a release (web/desktop)

  • Good first issue / Help wanted — Well-defined issues which are suitable for folks new to the codebase (web/desktop)

  • A11y / Meta / I18n / Privacy / Security — Issues which fall under these conceptual themes (which apply to many software projects and are not specific to Element)

  • Sponsored — Used internally by Element to denote issues with external funding (web/desktop)

Ad hoc labels (Z-)

We have reserved the Z- prefix for ad hoc labels. Please use #ededed colour for new Z- labels unless there is a good reason to use something else.

Any member of the core team is welcome to create labels beginning with Z- for any purpose, such as tracking personal areas of interest or providing a common way to label cross-repo initiatives. The prefix avoids interference with the project's main labels.

Help Wanted and good first issue

Help Wanted issues must be ready to develop. This means that

  • Product decision is made and clearly stated
  • Design decision is made and designs are attached if needed (note that external people may not have access to Figma)
  • This issue does not have any of the following labels:
    • X-Blocked
    • X-Needs-Design
    • X-Needs-Info
    • X-Needs-Product
    • X-Won't-Fix
  • This issue is suitable for someone who is a competent coder but may not be familiar Element.
  • If there are a number of technical approaches that could be taken, it is clear which approach we would expect.

good first issue must fulfil all the requirements for Help Wanted and:

  • Be suitable for someone who is new to coding
  • Have the Help Wanted label

Labs labels

When you add any labels for features in labs, you need to update the automation for those:

Team labels

Teams at Element can chose have their own labels to assist with automation and triage. These should be in the format Team: <name of team> and should match that team's colours.

Exceptions

You will see that some labels, such as A11y, Security and Sponsored do not fit with any of the labels above. Use them when their definitions are fulfilled by the issue. We will not rename these labels for now to ensure that they have high visibility.

Clone this wiki locally