From 79a3769d12c2461f8202a7732310129969500243 Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Sat, 4 Mar 2023 22:04:03 +0100 Subject: [PATCH 1/4] Add basic documentation for labels, including scoped labels Part of #22974 --- docs/content/doc/usage/labels.en-us.md | 38 ++++++++++++++++++++++++++ 1 file changed, 38 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..65512a862e34a --- /dev/null +++ b/docs/content/doc/usage/labels.en-us.md @@ -0,0 +1,38 @@ +--- +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 + +Issues and pull requests can be assigned labels for organization. + +## Creating Labels + +Labels can be created for a repository by going to Issues and choosing Labels. For organizations, labels available to all repositories can be created in the organization Settings. + +Labels have a name, color and optional description. + +If no labels exist a [default label set](../customizing-gitea/#labels) is suggested. + +## Scoped Labels + +Labels can be grouped using scopes indicated with a `/` separator in the name. When a label is named for example `scope/item`, the label display will changed to show the scope and item separately. + +Mutually exclusive labels can be created by enabling the Exclusive option for scoped labels. This makes it so only one label in the same scope can be assigned to an issue or pull request. + +## 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. From 294b7d48c336ab5f6983a6c06c62d6642d31b635 Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Sat, 4 Mar 2023 23:40:41 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: delvh --- docs/content/doc/usage/labels.en-us.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md index 65512a862e34a..887e202802dd3 100644 --- a/docs/content/doc/usage/labels.en-us.md +++ b/docs/content/doc/usage/labels.en-us.md @@ -15,21 +15,27 @@ menu: # Labels -Issues and pull requests can be assigned labels for organization. +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 choosing Labels. For organizations, labels available to all repositories can be created in the organization Settings. +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 name, color and optional description. +Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped labels` below). -If no labels exist a [default label set](../customizing-gitea/#labels) is suggested. +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 -Labels can be grouped using scopes indicated with a `/` separator in the name. When a label is named for example `scope/item`, the label display will changed to show the scope and item separately. - -Mutually exclusive labels can be created by enabling the Exclusive option for scoped labels. This makes it so only one label in the same scope can be assigned to an issue or pull request. +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`. ## Filtering by Label From 56e6f03f35b4b94a9f5961c8798df9e9fd47a0cd Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Sat, 4 Mar 2023 23:49:36 +0100 Subject: [PATCH 3/4] Update docs/content/doc/usage/labels.en-us.md Co-authored-by: delvh --- docs/content/doc/usage/labels.en-us.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md index 887e202802dd3..7e4dcfe3608c4 100644 --- a/docs/content/doc/usage/labels.en-us.md +++ b/docs/content/doc/usage/labels.en-us.md @@ -32,9 +32,9 @@ 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`. \ +A scoped label is a label that is marked as `exclusive` and contains `/` in its name (not at either end of the name). \ 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. \ +Issues can have at most one of these labels per scope, 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`. ## Filtering by Label From 88c6ed0a795ad7cf0efa8db64f71b06a42190bf4 Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Sun, 5 Mar 2023 00:14:14 +0100 Subject: [PATCH 4/4] Scoped labels don't have to be exclusive, don't break lines in paragraphs --- docs/content/doc/usage/labels.en-us.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md index 7e4dcfe3608c4..bf07c074edc68 100644 --- a/docs/content/doc/usage/labels.en-us.md +++ b/docs/content/doc/usage/labels.en-us.md @@ -19,23 +19,21 @@ You can use labels to classify issues and pull requests and to improve your over ## 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`. +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 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. +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 -You can decrease your error susceptibility by using scoped labels. \ -A scoped label is a label that is marked as `exclusive` and contains `/` in its name (not at either end of the name). \ -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. \ -Issues can have at most one of these labels per scope, 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`. +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