|
| 1 | +# Title & Label Taxonomy |
| 2 | + |
| 3 | +This document is the **source of truth** for how commits, pull requests and issues |
| 4 | +are titled and labeled in this repository. It is shared across all Filigran |
| 5 | +repositories (FiligranHQ, OpenCTI-Platform, OpenAEV-Platform, XTM-One-Platform, |
| 6 | +OpenGRC-Platform) so the whole ecosystem stays consistent. |
| 7 | + |
| 8 | +The machine-readable companion — each shared label's exact name, color and |
| 9 | +description — lives in [`.github/labels.yml`](labels.yml). Keep the two in sync |
| 10 | +when adding or renaming a shared label. |
| 11 | + |
| 12 | +## 1. Title convention (Conventional Commits) |
| 13 | + |
| 14 | +Every commit, pull request and issue title follows the |
| 15 | +[Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) |
| 16 | +specification, with a GitHub issue reference appended: |
| 17 | + |
| 18 | +``` |
| 19 | +type(scope?)!?: description (#issue) |
| 20 | +``` |
| 21 | + |
| 22 | +- `type` is one of: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, |
| 23 | + `test`, `build`, `ci`, `revert`. |
| 24 | +- `scope` is optional — a **lowercase** noun in parentheses naming the affected |
| 25 | + area, e.g. `feat(api):`, `fix(frontend):`, `docs(connectors):`. The scope |
| 26 | + **replaces** the old `[backend]` / `[frontend]` / `[component]` bracket |
| 27 | + prefixes, which are **discontinued**. |
| 28 | +- `!` is optional and marks a breaking change (e.g. `feat(api)!: ...`), optionally |
| 29 | + with a `BREAKING CHANGE:` footer. |
| 30 | +- `description` **starts with a lowercase letter** and has **no trailing period**. |
| 31 | + Preserve acronyms and proper nouns: `OpenCTI`, `OpenAEV`, `XTM One`, `OpenGRC`, |
| 32 | + `STIX`, `LLM`, `Docker`, `Redis`. |
| 33 | +- `(#issue)` is a **required reference on pull request titles** (the PR title |
| 34 | + becomes the squash-merge commit, so the reference lands on `master`/`main`). |
| 35 | + Issue titles omit it (the issue *is* the reference). |
| 36 | + |
| 37 | +Enforcement is preventive and lives at the organization (enterprise) level; the |
| 38 | +[`FiligranHQ/filigran-ci-tools` `pr-title-check`](https://github.com/FiligranHQ/filigran-ci-tools/tree/main/actions/pr-title-check) |
| 39 | +action validates the same format. **Renovate** pull requests are exempt. |
| 40 | + |
| 41 | +**Examples** |
| 42 | + |
| 43 | +``` |
| 44 | +feat(connectors): add CrowdStrike Falcon endpoint security integration (#1234) |
| 45 | +fix(frontend): correct file context limit handling (#1235) |
| 46 | +docs: update deployment guide (#1236) |
| 47 | +chore(ci): migrate dependency management to uv (#1237) |
| 48 | +feat(api)!: remove deprecated v1 endpoints (#1238) |
| 49 | +``` |
| 50 | + |
| 51 | +## 2. Type label (issues only — one per issue) |
| 52 | + |
| 53 | +The title `type` maps to a primary type label. **Primary type labels are applied |
| 54 | +to issues only:** |
| 55 | + |
| 56 | +| Title prefix | Type label | Color | |
| 57 | +|--------------|-----------------|--------| |
| 58 | +| `feat:` | `feature` | indigo | |
| 59 | +| `fix:` | `bug` | red | |
| 60 | +| `docs:` | `documentation` | blue | |
| 61 | + |
| 62 | +On issues, also set the GitHub **Type** field to match (`feat:` → `Feature`, |
| 63 | +`fix:` → `Bug`, every other type → `Task`). |
| 64 | + |
| 65 | +`chore:`, `style:`, `ci:`, `build:`, `perf:`, `refactor:`, `test:` and `revert:` |
| 66 | +are valid types; they do not each require a dedicated label (use a repository |
| 67 | +area/scope label where useful). `security` is a **label** (applied on top of the |
| 68 | +type, e.g. a `fix:` that closes a vulnerability), not a title type. |
| 69 | + |
| 70 | +> **Pull request labels are restricted to a small allowed set.** A pull request |
| 71 | +> carries only: |
| 72 | +> |
| 73 | +> - exactly **one ownership label — `filigran team` or `community`**; |
| 74 | +> - optionally **`vibe-coded`** — an AI-assisted change the author reviews before |
| 75 | +> requesting others' review; |
| 76 | +> - **language** labels (`javascript`, `python`, `java`, `go`, `rust`, |
| 77 | +> `typescript`, …) and the **`dependencies`** label, both applied automatically |
| 78 | +> by GitHub/Renovate. |
| 79 | +> |
| 80 | +> Every other label — primary **type** labels, **area/scope** labels and |
| 81 | +> **workflow/triage** labels — is **issue-only** and must **never** be added to a |
| 82 | +> pull request; remove any that appear. The PR's `type:` title prefix and its |
| 83 | +> linked issue already convey the type and the affected area. |
| 84 | +
|
| 85 | +## 3. Workflow & ownership labels |
| 86 | + |
| 87 | +- **Triage**: `needs triage`, `needs more info`, `solved`, `duplicate`, |
| 88 | + `wontfix`, `question`. |
| 89 | +- **Severity / size**: `critical`, `epic`, `tiny`, `regression`, |
| 90 | + `breaking-change`. |
| 91 | +- **Ownership**: `filigran team`, `community`, `community support`, |
| 92 | + `filigran support`, `partner support`, `enterprise edition`. |
| 93 | +- **Security**: `security`. |
| 94 | +- **PR review**: `vibe-coded` (an AI-assisted pull request the author reviews |
| 95 | + before requesting others' review). |
| 96 | +- **CLA**: `cla:pending`, `cla:signed`, `cla:exempt`. |
| 97 | +- **Automation**: `dependencies`, `javascript`, `python`, `java`, `do not merge`. |
| 98 | + |
| 99 | +See [`.github/labels.yml`](labels.yml) for the exact colors and descriptions. |
| 100 | + |
| 101 | +## 4. Area / scope labels (optional, may have several) |
| 102 | + |
| 103 | +On top of the shared labels above, repositories define their own area/scope |
| 104 | +labels (e.g. `frontend`, `backend`, `connector: <name>`, `collector: <name>`, |
| 105 | +`agents`, `authentication`). They add routing context and an issue may carry |
| 106 | +more than one. They are **issue-only** — like type and workflow labels, they are |
| 107 | +**not** added to pull requests (a PR carries only ownership, `vibe-coded` and the |
| 108 | +automatic language / `dependencies` labels). They are not listed in `labels.yml`. |
| 109 | + |
| 110 | +All label names are **lowercase**. Repository-specific labels use a neutral grey |
| 111 | +color (`ededed`); only the shared labels above carry color, so the common |
| 112 | +taxonomy stands out consistently across every Filigran repository. |
| 113 | + |
| 114 | +## 5. Deprecated labels — do not use |
| 115 | + |
| 116 | +- `enhancement` — use `feature`. |
| 117 | +- `feature request` / `feature-request` — use `feature` (+ `needs triage`). |
| 118 | +- `improvement` / `nice-to-have` — use `feature` + area labels. |
| 119 | + |
| 120 | +## 6. Quick checklist for a new issue / PR |
| 121 | + |
| 122 | +- [ ] Title follows `type(scope?)!?: description` (lowercase, no trailing period) |
| 123 | +- [ ] Pull request titles end with the `(#issue)` reference |
| 124 | +- [ ] **Issues only:** exactly one primary type label (`feature` / `bug` / |
| 125 | + `documentation`) matches the title prefix, and the GitHub **Type** field |
| 126 | + (Feature / Bug / Task) is set to match |
| 127 | +- [ ] **Pull requests:** one ownership label (`filigran team` / `community`), |
| 128 | + optionally `vibe-coded` and the automatic language / `dependencies` labels — |
| 129 | + and **no other label** (type, area/scope and workflow labels are issue-only) |
| 130 | +- [ ] Issues: area labels added where useful |
| 131 | +- [ ] No deprecated labels |
| 132 | +- [ ] Commits are signed and the PR is linked to an issue |
0 commit comments