From 6c2eb71e861bb557c2480851edfcd59d498cdd7d Mon Sep 17 00:00:00 2001 From: Samuel Hassine Date: Sun, 7 Jun 2026 14:25:40 +0200 Subject: [PATCH] chore: align with Filigran Conventional Commits & label conventions (#259) --- .github/ISSUE_TEMPLATE/bug_report.md | 78 +++++++------- .github/ISSUE_TEMPLATE/feature_request.md | 52 +++++----- .github/ISSUE_TEMPLATE/question.md | 22 ++++ .github/LABELS.md | 100 ++++++++++++++++++ .github/labels.yml | 121 ++++++++++++++++++++++ CONTRIBUTING.md | 62 +++++++++++ 6 files changed, 370 insertions(+), 65 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/LABELS.md create mode 100644 .github/labels.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 7ebd746..d5b9c2e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,39 +1,39 @@ ---- -name: Bug report -about: Create a report to help us improve OpenAEV -title: '' -labels: bug, needs triage -assignees: '' - ---- - -Please replace every line in curly brackets { like this } with an appropriate answer, and remove this line. - -## Description - -{ Please provide a clear and concise description of the bug. } - -## Environment - -1. OS (where OpenCTI server runs): { e.g. Mac OS 10, Windows 10, Ubuntu 16.4, etc. } -2. OpenCTI version: { e.g. OpenCTI 1.0.2 } -3. Other environment details: - -## Reproducible Steps - -Steps to create the smallest reproducible scenario: -1. { e.g. Run ... } -2. { e.g. Click ... } -3. { e.g. Error ... } - -## Expected Output - -{ Please describe what you expected to happen. } - -## Actual Output - -{ Please describe what actually happened. } - -## Additional information - -{ Any additional information, including logs or screenshots if you have any. } +--- +name: Bug report +about: Create a report to help us improve OpenAEV +title: 'fix: ' +labels: bug, needs triage +assignees: '' + +--- + +Please replace every line in curly brackets { like this } with an appropriate answer, and remove this line. + +## Description + +{ Please provide a clear and concise description of the bug. } + +## Environment + +1. OS (where OpenCTI server runs): { e.g. Mac OS 10, Windows 10, Ubuntu 16.4, etc. } +2. OpenCTI version: { e.g. OpenCTI 1.0.2 } +3. Other environment details: + +## Reproducible Steps + +Steps to create the smallest reproducible scenario: +1. { e.g. Run ... } +2. { e.g. Click ... } +3. { e.g. Error ... } + +## Expected Output + +{ Please describe what you expected to happen. } + +## Actual Output + +{ Please describe what actually happened. } + +## Additional information + +{ Any additional information, including logs or screenshots if you have any. } diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 5b535f8..b2b4c9c 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,26 +1,26 @@ ---- -name: Feature request -about: Ask for a new feature to be implemented in OpenAEV -title: '' -labels: feature, needs triage -assignees: '' - ---- - -Please replace every line in curly brackets { like this } with appropriate answers, and remove this line. - -## Problem to Solve - -{ Please describe the problem you would like to solve. } - -## Current Workaround - -{ Please describe how you currently solve or work around this problem, given OpenAEV's limitation. } - -## Proposed Solution - -{ Please describe the solution you would like OpenAEV to provide, to solve the problem above. } - -## Additional Information - -{ Any additional information, including logs or screenshots if you have any. } +--- +name: Feature request +about: Ask for a new feature to be implemented in OpenAEV +title: 'feat: ' +labels: feature, needs triage +assignees: '' + +--- + +Please replace every line in curly brackets { like this } with appropriate answers, and remove this line. + +## Problem to Solve + +{ Please describe the problem you would like to solve. } + +## Current Workaround + +{ Please describe how you currently solve or work around this problem, given OpenAEV's limitation. } + +## Proposed Solution + +{ Please describe the solution you would like OpenAEV to provide, to solve the problem above. } + +## Additional Information + +{ Any additional information, including logs or screenshots if you have any. } diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..c3668ad --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,22 @@ +--- +name: Question +about: Ask a question about the project +title: '' +labels: needs triage, question +assignees: '' + +--- + +## Prerequisites + +- [ ] I read the documentation and didn't find anything relevant to my problem. +- [ ] I went through old GitHub issues and couldn't find anything relevant. +- [ ] I searched the web and didn't find anything relevant. + +## Description + + + +## Additional information + + diff --git a/.github/LABELS.md b/.github/LABELS.md new file mode 100644 index 0000000..9f7cdfe --- /dev/null +++ b/.github/LABELS.md @@ -0,0 +1,100 @@ +# Title & Label Taxonomy + +This document is the **source of truth** for how commits, pull requests and issues +are titled and labeled in this repository. It is shared across all Filigran +repositories (FiligranHQ, OpenCTI-Platform, OpenAEV-Platform, XTM-One-Platform, +OpenGRC-Platform) so the whole ecosystem stays consistent. + +The machine-readable companion — each shared label's exact name, color and +description — lives in [`.github/labels.yml`](labels.yml). Keep the two in sync +when adding or renaming a shared label. + +## 1. Title convention (Conventional Commits) + +Every commit, pull request and issue title follows the +[Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) +specification, with a GitHub issue reference appended: + +``` +type(scope?)!?: description (#issue) +``` + +- `type` is one of: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, + `test`, `build`, `ci`, `revert`. +- `scope` is optional — a **lowercase** noun in parentheses naming the affected + area, e.g. `feat(api):`, `fix(frontend):`, `docs(connectors):`. The scope + **replaces** the old `[backend]` / `[frontend]` / `[component]` bracket + prefixes, which are **discontinued**. +- `!` is optional and marks a breaking change (e.g. `feat(api)!: ...`), optionally + with a `BREAKING CHANGE:` footer. +- `description` **starts with a lowercase letter** and has **no trailing period**. + Preserve acronyms and proper nouns: `OpenCTI`, `OpenAEV`, `XTM One`, `OpenGRC`, + `STIX`, `LLM`, `Docker`, `Redis`. +- `(#issue)` is a **required reference on pull request titles** (the PR title + becomes the squash-merge commit, so the reference lands on `master`/`main`). + Issue titles omit it (the issue *is* the reference). + +Enforcement is preventive and lives at the organization (enterprise) level; the +[`FiligranHQ/filigran-ci-tools` `pr-title-check`](https://github.com/FiligranHQ/filigran-ci-tools/tree/main/actions/pr-title-check) +action validates the same format. **Renovate** pull requests are exempt. + +**Examples** + +``` +feat(connectors): add CrowdStrike Falcon endpoint security integration (#1234) +fix(frontend): correct file context limit handling (#1235) +docs: update deployment guide (#1236) +chore(ci): migrate dependency management to uv (#1237) +feat(api)!: remove deprecated v1 endpoints (#1238) +``` + +## 2. Type label (one per issue) + +The title `type` maps to a primary type label: + +| Title prefix | Type label | Color | +|--------------|-----------------|--------| +| `feat:` | `feature` | indigo | +| `fix:` | `bug` | red | +| `docs:` | `documentation` | blue | + +`chore:`, `style:`, `ci:`, `build:`, `perf:`, `refactor:`, `test:` and `revert:` +are valid types; they do not each require a dedicated label (use a repository +area/scope label where useful). `security` is a **label** (applied on top of the +type, e.g. a `fix:` that closes a vulnerability), not a title type. + +## 3. Workflow & ownership labels + +- **Triage**: `needs triage`, `needs more info`, `solved`, `duplicate`, + `wontfix`, `question`. +- **Severity / size**: `critical`, `epic`, `tiny`, `regression`, + `breaking-change`. +- **Ownership**: `filigran team`, `community`, `community support`, + `filigran support`, `partner support`, `enterprise edition`. +- **Security**: `security`. +- **CLA**: `cla:pending`, `cla:signed`, `cla:exempt`. +- **Automation**: `dependencies`, `javascript`, `python`, `java`, `do not merge`. + +See [`.github/labels.yml`](labels.yml) for the exact colors and descriptions. + +## 4. Area / scope labels (optional, may have several) + +On top of the shared labels above, repositories define their own area/scope +labels (e.g. `frontend`, `backend`, `connector: `, `collector: `, +`agents`, `authentication`). They add routing context and an issue may carry +more than one. They are not listed in `labels.yml`. + +## 5. Deprecated labels — do not use + +- `enhancement` — use `feature`. +- `feature request` / `feature-request` — use `feature` (+ `needs triage`). +- `improvement` / `nice-to-have` — use `feature` + area labels. + +## 6. Quick checklist for a new issue / PR + +- [ ] Title follows `type(scope?)!?: description` (lowercase, no trailing period) +- [ ] Pull request titles end with the `(#issue)` reference +- [ ] Exactly one primary type label matches the title prefix +- [ ] Area labels added where useful +- [ ] No deprecated labels +- [ ] Commits are signed and the PR is linked to an issue diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..c6f31e0 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,121 @@ +# Canonical Filigran label palette — shared across all Filigran repositories +# (FiligranHQ, OpenCTI-Platform, OpenAEV-Platform, XTM-One-Platform, OpenGRC-Platform). +# +# This file is the machine-readable companion to .github/LABELS.md and the source +# of truth for the *shared* labels' name, color and description. Repositories may +# define additional area/scope labels on top of this set; those are intentionally +# not listed here. +# +# Colors mirror the canonical Filigran palette (anchored on OpenCTI, the most +# mature repository). It is a root-level YAML list of {name, color, description} +# entries — the manifest format consumed directly by both EndBug/label-sync and +# micnncim/action-label-syncer (neither expects a top-level `labels:` key). +# +# Reference manifest: do NOT enable destructive deletion (delete-other-labels) +# when wiring up a sync, so each repository's own area/scope labels are preserved. + +# ── Primary type labels (map to the Conventional Commits title prefix) ── +- name: feature + color: "6a3eef" + description: "Type: new feature or capability (feat:)." +- name: bug + color: "d73a4a" + description: "Type: something isn't working (fix:)." +- name: documentation + color: "0075ca" + description: "Type: documentation only (docs:)." +- name: security + color: "d93f0b" + description: "Security vulnerability, hardening or guardrail." + +# ── Workflow / triage labels ── +- name: needs triage + color: "906a2d" + description: "Needs triage from the Filigran product team." +- name: needs more info + color: "906a2d" + description: "More information is required to triage or resolve." +- name: solved + color: "0e8a16" + description: "Resolved (should be linked to the solving PR)." +- name: duplicate + color: "cfd3d7" + description: "This issue or pull request already exists." +- name: wontfix + color: "cfd3d7" + description: "This will not be worked on." +- name: question + color: "cc317c" + description: "Further information is requested." +- name: critical + color: "a40500" + description: "Critical issue to fix ASAP." +- name: epic + color: "d96d39" + description: "Large issue that will be split into several chunks." +- name: tiny + color: "86cb6b" + description: "Tiny change (less than a week to solve)." +- name: regression + color: "1f47d8" + description: "Regression of a previously working feature." +- name: breaking-change + color: "e99695" + description: "Introduces a potential breaking change." +- name: "do not merge" + color: "02f4d4" + description: "Do not merge until this label is removed." +- name: good first issue + color: "5319e7" + description: "Good issue for first-time contributors." +- name: test automation + color: "586ca9" + description: "Linked to test automation implementation." +- name: architecture improvement + color: "6d155d" + description: "Architecture refactor or improvement is needed." + +# ── Ownership / community labels ── +- name: filigran team + color: "4a0c43" + description: "Item from the Filigran team." +- name: community + color: "268e45" + description: "Contribution from the community." +- name: community support + color: "ffa500" + description: "Feature developed and maintained by the community." +- name: filigran support + color: "298d96" + description: "Feature developed and maintained by Filigran." +- name: partner support + color: "c8c226" + description: "Feature developed and maintained by a third-party vendor." +- name: enterprise edition + color: "b819f4" + description: "Feature part of the Enterprise Edition license." + +# ── Contributor License Agreement ── +- name: "cla:pending" + color: "fbca04" + description: "CLA signature required." +- name: "cla:signed" + color: "0e8a16" + description: "CLA has been signed." +- name: "cla:exempt" + color: "5319e7" + description: "CLA not required (Filigran employee)." + +# ── PR / dependency automation ── +- name: dependencies + color: "0366d6" + description: "Pull requests that update a dependency file." +- name: javascript + color: "168700" + description: "Pull requests that update JavaScript code." +- name: python + color: "2b67c6" + description: "Pull requests that update Python code." +- name: java + color: "ffa221" + description: "Pull requests that update Java code." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4a0577c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing + +Thank you for considering making a contribution to this project. Any contribution +that helps us improve is valuable and much appreciated. + +Do not hesitate to reach out by [email](mailto:contact@filigran.io) or on our +[Slack channel](https://community.filigran.io). + +## How can you contribute? + +Many contributions don't imply coding. Contributions can range from a suggestion +for improving documentation, requesting a new feature, reporting a bug, to +developing features or fixing bugs yourself. + +* To report a bug or request a feature, open an issue using the provided + templates. +* You can look through opened issues and help triage them (ask for more + information, suggest workarounds, suggest labels, etc.). +* If you are interested in contributing code, fork the repository, create a + branch, and open a pull request. + + +## Commit, pull request & issue conventions + +To keep the backlog consistent and searchable across all Filigran projects, this +repository follows a shared title and label convention. The full taxonomy lives +in [`.github/LABELS.md`](.github/LABELS.md). In short: + +* **Titles** — All commit, pull request and issue titles follow the + [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) + specification with a GitHub issue reference: + `type(scope?)!?: description (#issue)` (e.g. + `feat(api): add bulk export endpoint (#1234)`). The description starts with a + lowercase letter and has no trailing period; preserve acronyms and proper + nouns. Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, + `test`, `build`, `ci`, `revert`. + +* **No more bracket prefixes** — The old `[backend]` / `[frontend]` / + `[component]` prefixes are **discontinued**; use a Conventional Commits scope + instead (e.g. `fix(backend): ...`). + +* **GitHub reference** — Pull request titles **must** end with the related issue + reference, e.g. `(#1234)` (the PR title becomes the squash-merge commit). Every + pull request must be linked to an issue. Enforcement is preventive and applied + at the organization level; **Renovate** pull requests are exempt. + +* **Signed commits** — All commits must be signed. See the + [GitHub documentation on signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). + +* **Labels** — Every issue carries one primary type label matching its title + prefix (`feature` for `feat:`, `bug` for `fix:`, `documentation` for `docs:`) + plus optional area labels. Do not use the deprecated `enhancement` / + `feature request` labels — use `feature`. See + [`.github/LABELS.md`](.github/LABELS.md) for the shared palette + ([`.github/labels.yml`](.github/labels.yml)). + + +## How can you get in touch for other questions? + +If you need support or wish to engage a discussion about the project, feel free +to join us on our [Slack channel](https://community.filigran.io). You can also +send us an [email](mailto:contact@filigran.io).