Skip to content

Commit a94f0fd

Browse files
SamuelHassineSamuelHassine
authored
chore: align with Filigran Conventional Commits & label conventions (#580) (#581)
1 parent 99a52e2 commit a94f0fd

6 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: Bug report
3+
about: Create a bug report to help us improve
4+
title: 'fix: '
5+
labels: needs triage, bug
6+
assignees: ''
7+
type: bug
8+
9+
---
10+
11+
## Description
12+
13+
<!-- Please provide a clear and concise description of the bug. -->
14+
15+
## Environment
16+
17+
1. OS: { e.g. macOS 14, Windows 11, Ubuntu 22.04, etc. }
18+
2. Version: { e.g. 1.0.0 }
19+
3. Other environment details:
20+
21+
## Reproducible steps
22+
23+
Steps to create the smallest reproducible scenario:
24+
1. { e.g. Run ... }
25+
2. { e.g. Click ... }
26+
3. { e.g. Error ... }
27+
28+
## Expected output
29+
30+
<!-- Please describe what you expected to happen. -->
31+
32+
## Actual output
33+
34+
<!-- Please describe what actually happened. -->
35+
36+
## Additional information
37+
38+
<!-- Any additional information, including logs or screenshots if you have any. -->

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new feature or capability
4+
title: 'feat: '
5+
labels: needs triage, feature
6+
assignees: ''
7+
type: feature
8+
9+
---
10+
11+
## Use case
12+
13+
<!-- Please describe the use case for which you need a solution. -->
14+
15+
## Current workaround
16+
17+
<!-- Please describe how you currently solve or work around this problem. -->
18+
19+
## Proposed solution
20+
21+
<!-- Please describe the solution you would like to be provided. -->
22+
23+
## Additional information
24+
25+
<!-- Any additional information, including logs or screenshots if you have any. -->

‎.github/ISSUE_TEMPLATE/question.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: Question
3+
about: Ask a question about the project
4+
title: ''
5+
labels: needs triage, question
6+
assignees: ''
7+
8+
---
9+
10+
## Prerequisites
11+
12+
- [ ] I read the documentation and didn't find anything relevant to my problem.
13+
- [ ] I went through old GitHub issues and couldn't find anything relevant.
14+
- [ ] I searched the web and didn't find anything relevant.
15+
16+
## Description
17+
18+
<!-- Please provide a clear and concise description of your question. -->
19+
20+
## Additional information
21+
22+
<!-- Any additional information, including logs or screenshots if you have any. -->

‎.github/LABELS.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
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 (one per issue)
52+
53+
The title `type` maps to a primary type label:
54+
55+
| Title prefix | Type label | Color |
56+
|--------------|-----------------|--------|
57+
| `feat:` | `feature` | indigo |
58+
| `fix:` | `bug` | red |
59+
| `docs:` | `documentation` | blue |
60+
61+
`chore:`, `style:`, `ci:`, `build:`, `perf:`, `refactor:`, `test:` and `revert:`
62+
are valid types; they do not each require a dedicated label (use a repository
63+
area/scope label where useful). `security` is a **label** (applied on top of the
64+
type, e.g. a `fix:` that closes a vulnerability), not a title type.
65+
66+
## 3. Workflow & ownership labels
67+
68+
- **Triage**: `needs triage`, `needs more info`, `solved`, `duplicate`,
69+
`wontfix`, `question`.
70+
- **Severity / size**: `critical`, `epic`, `tiny`, `regression`,
71+
`breaking-change`.
72+
- **Ownership**: `filigran team`, `community`, `community support`,
73+
`filigran support`, `partner support`, `enterprise edition`.
74+
- **Security**: `security`.
75+
- **CLA**: `cla:pending`, `cla:signed`, `cla:exempt`.
76+
- **Automation**: `dependencies`, `javascript`, `python`, `java`, `do not merge`.
77+
78+
See [`.github/labels.yml`](labels.yml) for the exact colors and descriptions.
79+
80+
## 4. Area / scope labels (optional, may have several)
81+
82+
On top of the shared labels above, repositories define their own area/scope
83+
labels (e.g. `frontend`, `backend`, `connector: <name>`, `collector: <name>`,
84+
`agents`, `authentication`). They add routing context and an issue may carry
85+
more than one. They are not listed in `labels.yml`.
86+
87+
## 5. Deprecated labels — do not use
88+
89+
- `enhancement` — use `feature`.
90+
- `feature request` / `feature-request` — use `feature` (+ `needs triage`).
91+
- `improvement` / `nice-to-have` — use `feature` + area labels.
92+
93+
## 6. Quick checklist for a new issue / PR
94+
95+
- [ ] Title follows `type(scope?)!?: description` (lowercase, no trailing period)
96+
- [ ] Pull request titles end with the `(#issue)` reference
97+
- [ ] Exactly one primary type label matches the title prefix
98+
- [ ] Area labels added where useful
99+
- [ ] No deprecated labels
100+
- [ ] Commits are signed and the PR is linked to an issue

‎.github/labels.yml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Canonical Filigran label palette — shared across all Filigran repositories
2+
# (FiligranHQ, OpenCTI-Platform, OpenAEV-Platform, XTM-One-Platform, OpenGRC-Platform).
3+
#
4+
# This file is the machine-readable companion to .github/LABELS.md and the source
5+
# of truth for the *shared* labels' name, color and description. Repositories may
6+
# define additional area/scope labels on top of this set; those are intentionally
7+
# not listed here.
8+
#
9+
# Colors mirror the canonical Filigran palette (anchored on OpenCTI, the most
10+
# mature repository). It is a root-level YAML list of {name, color, description}
11+
# entries — the manifest format consumed directly by both EndBug/label-sync and
12+
# micnncim/action-label-syncer (neither expects a top-level `labels:` key).
13+
#
14+
# Reference manifest: do NOT enable destructive deletion (delete-other-labels)
15+
# when wiring up a sync, so each repository's own area/scope labels are preserved.
16+
17+
# ── Primary type labels (map to the Conventional Commits title prefix) ──
18+
- name: feature
19+
color: "6a3eef"
20+
description: "Type: new feature or capability (feat:)."
21+
- name: bug
22+
color: "d73a4a"
23+
description: "Type: something isn't working (fix:)."
24+
- name: documentation
25+
color: "0075ca"
26+
description: "Type: documentation only (docs:)."
27+
- name: security
28+
color: "d93f0b"
29+
description: "Security vulnerability, hardening or guardrail."
30+
31+
# ── Workflow / triage labels ──
32+
- name: needs triage
33+
color: "906a2d"
34+
description: "Needs triage from the Filigran product team."
35+
- name: needs more info
36+
color: "906a2d"
37+
description: "More information is required to triage or resolve."
38+
- name: solved
39+
color: "0e8a16"
40+
description: "Resolved (should be linked to the solving PR)."
41+
- name: duplicate
42+
color: "cfd3d7"
43+
description: "This issue or pull request already exists."
44+
- name: wontfix
45+
color: "cfd3d7"
46+
description: "This will not be worked on."
47+
- name: question
48+
color: "cc317c"
49+
description: "Further information is requested."
50+
- name: critical
51+
color: "a40500"
52+
description: "Critical issue to fix ASAP."
53+
- name: epic
54+
color: "d96d39"
55+
description: "Large issue that will be split into several chunks."
56+
- name: tiny
57+
color: "86cb6b"
58+
description: "Tiny change (less than a week to solve)."
59+
- name: regression
60+
color: "1f47d8"
61+
description: "Regression of a previously working feature."
62+
- name: breaking-change
63+
color: "e99695"
64+
description: "Introduces a potential breaking change."
65+
- name: "do not merge"
66+
color: "02f4d4"
67+
description: "Do not merge until this label is removed."
68+
- name: good first issue
69+
color: "5319e7"
70+
description: "Good issue for first-time contributors."
71+
- name: test automation
72+
color: "586ca9"
73+
description: "Linked to test automation implementation."
74+
- name: architecture improvement
75+
color: "6d155d"
76+
description: "Architecture refactor or improvement is needed."
77+
78+
# ── Ownership / community labels ──
79+
- name: filigran team
80+
color: "4a0c43"
81+
description: "Item from the Filigran team."
82+
- name: community
83+
color: "268e45"
84+
description: "Contribution from the community."
85+
- name: community support
86+
color: "ffa500"
87+
description: "Feature developed and maintained by the community."
88+
- name: filigran support
89+
color: "298d96"
90+
description: "Feature developed and maintained by Filigran."
91+
- name: partner support
92+
color: "c8c226"
93+
description: "Feature developed and maintained by a third-party vendor."
94+
- name: enterprise edition
95+
color: "b819f4"
96+
description: "Feature part of the Enterprise Edition license."
97+
98+
# ── Contributor License Agreement ──
99+
- name: "cla:pending"
100+
color: "fbca04"
101+
description: "CLA signature required."
102+
- name: "cla:signed"
103+
color: "0e8a16"
104+
description: "CLA has been signed."
105+
- name: "cla:exempt"
106+
color: "5319e7"
107+
description: "CLA not required (Filigran employee)."
108+
109+
# ── PR / dependency automation ──
110+
- name: dependencies
111+
color: "0366d6"
112+
description: "Pull requests that update a dependency file."
113+
- name: javascript
114+
color: "168700"
115+
description: "Pull requests that update JavaScript code."
116+
- name: python
117+
color: "2b67c6"
118+
description: "Pull requests that update Python code."
119+
- name: java
120+
color: "ffa221"
121+
description: "Pull requests that update Java code."

‎CONTRIBUTING.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Contributing
2+
3+
Thank you for considering making a contribution to this project. Any contribution
4+
that helps us improve is valuable and much appreciated.
5+
6+
Do not hesitate to reach out by [email](mailto:contact@filigran.io) or on our
7+
[Slack channel](https://community.filigran.io).
8+
9+
## How can you contribute?
10+
11+
Many contributions don't imply coding. Contributions can range from a suggestion
12+
for improving documentation, requesting a new feature, reporting a bug, to
13+
developing features or fixing bugs yourself.
14+
15+
* To report a bug or request a feature, open an issue using the provided
16+
templates.
17+
* You can look through opened issues and help triage them (ask for more
18+
information, suggest workarounds, suggest labels, etc.).
19+
* If you are interested in contributing code, fork the repository, create a
20+
branch, and open a pull request.
21+
22+
<!-- filigran-conventions:start -->
23+
## Commit, pull request & issue conventions
24+
25+
To keep the backlog consistent and searchable across all Filigran projects, this
26+
repository follows a shared title and label convention. The full taxonomy lives
27+
in [`.github/LABELS.md`](.github/LABELS.md). In short:
28+
29+
* **Titles** — All commit, pull request and issue titles follow the
30+
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
31+
specification with a GitHub issue reference:
32+
`type(scope?)!?: description (#issue)` (e.g.
33+
`feat(api): add bulk export endpoint (#1234)`). The description starts with a
34+
lowercase letter and has no trailing period; preserve acronyms and proper
35+
nouns. Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`,
36+
`test`, `build`, `ci`, `revert`.
37+
38+
* **No more bracket prefixes** — The old `[backend]` / `[frontend]` /
39+
`[component]` prefixes are **discontinued**; use a Conventional Commits scope
40+
instead (e.g. `fix(backend): ...`).
41+
42+
* **GitHub reference** — Pull request titles **must** end with the related issue
43+
reference, e.g. `(#1234)` (the PR title becomes the squash-merge commit). Every
44+
pull request must be linked to an issue. Enforcement is preventive and applied
45+
at the organization level; **Renovate** pull requests are exempt.
46+
47+
* **Signed commits** — All commits must be signed. See the
48+
[GitHub documentation on signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
49+
50+
* **Labels** — Every issue carries one primary type label matching its title
51+
prefix (`feature` for `feat:`, `bug` for `fix:`, `documentation` for `docs:`)
52+
plus optional area labels. Do not use the deprecated `enhancement` /
53+
`feature request` labels — use `feature`. See
54+
[`.github/LABELS.md`](.github/LABELS.md) for the shared palette
55+
([`.github/labels.yml`](.github/labels.yml)).
56+
<!-- filigran-conventions:end -->
57+
58+
## How can you get in touch for other questions?
59+
60+
If you need support or wish to engage a discussion about the project, feel free
61+
to join us on our [Slack channel](https://community.filigran.io). You can also
62+
send us an [email](mailto:contact@filigran.io).

0 commit comments

Comments
 (0)