Skip to content

Issue labelling

Jump to bottom
Kat Gerasimova edited this page May 10, 2022 · 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:

    • S-Critical: Prevents work, causes data loss and/or has no workaround (web/desktop)
    • S-Major: Severely degrades major functionality or product features, with no satisfactory workaround (web/desktop)
    • S-Minor: Impairs non-critical functionality or suitable workarounds exist (web/desktop)
    • S-Tolerable: Low/no impact on users (web/desktop)

  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