From 5d621fe9a7f27b5168db22dc38423b71037bcae0 Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Sun, 5 Mar 2023 13:35:12 +0100 Subject: [PATCH] Add basic documentation for labels, including scoped labels (#23304) Part of #22974 --------- Co-authored-by: delvh --- docs/content/doc/usage/labels.en-us.md | 42 ++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/content/doc/usage/labels.en-us.md diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md new file mode 100644 index 0000000000000..bf07c074edc68 --- /dev/null +++ b/docs/content/doc/usage/labels.en-us.md @@ -0,0 +1,42 @@ +--- +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 + +For repositories, labels can be created 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 repository, 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 repository. + +## Scoped Labels + +A scoped label is a label that contains `/` in its name (not at either end of the name). For example labels `kind/bug` and `kind/enhancement` both have scope `kind`. Such labels will display the scope with slightly darker color. + +The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`. + +Scoped labels can be marked as exclusive. This ensures at most a single label with the same scope is assigned to an issue or pull request. For example, if `kind/bug` and `kind/enhancement` are marked exclusive, an issue can only be classified as a bug or an enhancement. + +## 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.