From 2aae2890c4df58276053d7822dd1914d4f1042fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9dric=20Barreteau?=
 <cbarrete@users.noreply.github.com>
Date: Sun, 2 Feb 2025 17:39:40 -0500
Subject: [PATCH] Add documentation on labels

Closes #667.
---
 docs/concepts/labels.md | 22 ++++++++++++++++++++++
 website/sidebars.ts     |  1 +
 2 files changed, 23 insertions(+)
 create mode 100644 docs/concepts/labels.md

diff --git a/docs/concepts/labels.md b/docs/concepts/labels.md
new file mode 100644
index 000000000000..7411ec9fa046
--- /dev/null
+++ b/docs/concepts/labels.md
@@ -0,0 +1,22 @@
+---
+id: labels
+title: Labels
+---
+
+The term "label" is a little overloaded in Buck2. It can refer to:
+
+- A target identifier composed of its name, cell and path.
+- One or more tag-like strings attached to a test target.
+
+For the first definition of label, the target label is determined by
+where it's defined, as well as its `name` attribute. Labels are exposed
+in the build API via the
+[`Label`](https://buck2.build/docs/api/build/Label/) type, which can be
+used in rule implementations and BXL scripts.
+
+For the second definition of label, test rules expose a `label`
+attribute, which is a list of strings. Specific labels can be targeted
+when running `buck2 test` by adding the `--exclude`/`--include` flags.
+See the [test execution
+docs](https://buck2.build/docs/rule_authors/test_execution/) for more
+information.
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 8549e2fd40f3..07be6c9c2546 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -64,6 +64,7 @@ export const sidebars: SidebarsConfig = {
         'concepts/buck_out',
         'concepts/visibility',
         'concepts/daemon',
+        'concepts/labels',
         'concepts/isolation_dir',
         'concepts/buckconfig',
         'concepts/configurations',