Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add basic documentation for labels, including scoped labels #23304

Merged
merged 4 commits into from
Mar 5, 2023
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/content/doc/usage/labels.en-us.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
date: "2023-03-04T19:00:00+00:00"
title: "Usage: Labels"
slug: "labels"
weight: 13
toc: false
draft: false
menu:
sidebar:
parent: "usage"
name: "Labels"
weight: 13
identifier: "labels"
---

# Labels

You can use labels to classify issues and pull requests and to improve your overview over them.

## Creating Labels

Labels can be created for a repository by going to `Issues` and clicking on `Labels`. \
For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. \
Organization-wide labels can be created in the organization `Settings`.

Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped labels` below).

When you create a repo, you can ensure certain labels exist by using the `Issue Labels` option. \
This option lists a number of available label sets that are [configured globally on your instance](../customizing-gitea/#labels). \
Its contained labels will all be created as well while creating the repo.

## Scoped Labels

You can decrease your error susceptibility by using scoped labels. \
A scoped label is a label containing `/` in its name (not at either end of the name) and marking the label as `exclusive`. \
For example, if label `A` is called `scope/item`, label `B` is called `scope/second-item`, and both are marked as `exclusive`, an issue cannot be labeled with both `A` and `B` at the same time. \
Such an issue can have at most one of these labels, or none. \
The scope of a label is determined based on the **last** `/`, so for example the scope of label `subscope/subscope2/item` would be `subscope/subscope2`.
brechtvl marked this conversation as resolved.
Show resolved Hide resolved

## Filtering by Label

Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.

By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.
delvh marked this conversation as resolved.
Show resolved Hide resolved