| 1 | # Labels |
| 2 | |
| 3 | vLLM applies most labels automatically. Three systems do the work: |
| 4 | |
| 5 | | | Config | Applies to | |
| 6 | | --- | --- | --- | |
| 7 | | Mergify | `.github/mergify.yml` | pull requests, by changed file path or title | |
| 8 | | GitHub Action | `.github/workflows/issue_autolabel.yml` | issues, by title keyword | |
| 9 | | Issue templates | `.github/ISSUE_TEMPLATE/*.yml` | issues, by which template was used | |
| 10 | |
| 11 | A label that none of them applies has to be applied by hand, and in practice |
| 12 | that means it mostly doesn't get applied at all. |
| 13 | |
| 14 | A template's `labels:` field must name a label that already exists — GitHub |
| 15 | silently skips one that doesn't, with no error anywhere. |
| 16 | |
| 17 | `mergify.yml` also drives reviewer auto-assignment; see |
| 18 | [Collaboration](../governance/collaboration.md) for adding yourself as a |
| 19 | maintainer of an area. |
| 20 | |
| 21 | ## Adding a label |
| 22 | |
| 23 | A new label needs three things. If it can't have all three, don't create it. |
| 24 | |
| 25 | 1. **An audience.** Someone has to want to filter on it. "It would be nice to |
| 26 | know" isn't enough. |
| 27 | 2. **An owner.** A person or SIG who triages that queue. Without one the label |
| 28 | accumulates issues nobody reads. |
| 29 | 3. **A rule, in the same PR.** If you can't write a precise rule, the label |
| 30 | depends on humans remembering it exists. |
| 31 | |
| 32 | ## Measure before you argue |
| 33 | |
| 34 | Volume claims should come from the repo, not from intuition. vLLM squash-merges, |
| 35 | so one commit on `main` is one PR: |
| 36 | |
| 37 | ```bash |
| 38 | git log --since="6 months ago" --oneline -- <path> | wc -l |
| 39 | ``` |
| 40 | |
| 41 | For reference, at the time of writing: `speculative-decoding` 81, `llama` 85, |
| 42 | `mistral` 72, `tpu` 14. A subsystem in that range clears the bar comfortably. |
| 43 | Something in the low teens needs a stronger argument than volume. |
| 44 | |
| 45 | The same applies to claiming a rule is too broad. Check what it actually labels |
| 46 | before rewriting it: |
| 47 | |
| 48 | ```bash |
| 49 | gh pr list --repo vllm-project/vllm --state merged --limit 200 \ |
| 50 | --json number,title,labels |
| 51 | ``` |
| 52 | |
| 53 | Several rules in this repo have been called over-broad on inspection and turned |
| 54 | out to be accurate when measured. |
| 55 | |
| 56 | ## Writing conditions |
| 57 | |
| 58 | **`files=` is exact equality. `files~=` is a regex.** Writing a pattern after |
| 59 | `=` compares the pattern text to each filename, so it can never match: |
| 60 | |
| 61 | ```yaml |
| 62 | - files=^examples/features/speculative_decoding/ # never fires |
| 63 | - files~=^examples/features/speculative_decoding/ # correct |
| 64 | ``` |
| 65 | |
| 66 | **Anchor file patterns.** An unanchored fragment matches far more than intended |
| 67 | — `files~=cuda` also matches `requirements/cuda.txt`. |
| 68 | |
| 69 | **Watch for names that contain other names.** `midashenglm.py` contains "glm" |
| 70 | but is unrelated to GLM, so the `glm` rule anchors to the start of the filename. |
| 71 | |
| 72 | **Keep an eye on where model code lives.** Newer models live in |
| 73 | `vllm/models/<model>/` rather than `vllm/model_executor/models/`. A rule that |
| 74 | only knows the old location silently stops matching. |
| 75 | |
| 76 | **Prefer titles for issue keywords.** Issue bodies contain pasted `collect_env` |
| 77 | output, tracebacks and configs that mention unrelated hardware and libraries. |
| 78 | Body matching tags the reporter's environment rather than the topic. |
| 79 | |
| 80 | **Single words go in `keywords`, phrases in `substrings`.** `keywords` matches on |
| 81 | word boundaries, which stops a term firing inside a longer word but also misses |
| 82 | ordinary variations — `structured output` will not match "structured outputs". |
| 83 | |
| 84 | ## Keeping rules honest |
| 85 | |
| 86 | `tools/pre_commit/check_label_rules.py` fails if any file condition in |
| 87 | `mergify.yml` matches nothing in the tree. It runs via pre-commit when that file |
| 88 | changes. This catches conditions that were correct when written and rotted when |
| 89 | the code moved. |
| 90 | |
| 91 | ## Not everything needs a label |
| 92 | |
| 93 | Triage and workflow labels — `bug`, `stale`, `ready`, `RFC`, `needs-rebase` — |
| 94 | and the bot provenance tags are applied by other mechanisms or by hand, and are |
| 95 | intentionally outside this system. |