diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index adff8a90..e65ac253 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,40 +1,40 @@ ---- -name: Bug report -about: Create a bug report to help us improve OpenAEV -title: '' -labels: bug, needs triage -assignees: '' - ---- - -## Description - - - -## Environment - -1. OS (where OpenAEV server runs): { e.g. Mac OS 10, Windows 10, Ubuntu 16.4, etc. } -2. OpenAEV version: { e.g. OpenAEV 1.0.2 } -3. OpenAEV client: { e.g. frontend or python } -4. 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 - - - -## Actual Output - - - -## Additional information - - - -## Screenshots (optional) +--- +name: Bug report +about: Create a bug report to help us improve OpenAEV +title: 'fix: ' +labels: bug, needs triage +assignees: '' + +--- + +## Description + + + +## Environment + +1. OS (where OpenAEV server runs): { e.g. Mac OS 10, Windows 10, Ubuntu 16.4, etc. } +2. OpenAEV version: { e.g. OpenAEV 1.0.2 } +3. OpenAEV client: { e.g. frontend or python } +4. 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 + + + +## Actual Output + + + +## Additional information + + + +## Screenshots (optional) diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 765515df..efc1640e 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,36 +1,36 @@ ---- -name: Feature request -about: Ask for a new feature to be implemented in OpenAEV -title: '' -labels: feature, needs triage -assignees: '' - ---- - -## Context - - - -## Use case - - - -## Current Workaround - - - -## Proposed Solution - - - -## Additional Information - - - -## If the feature request is approved, would you be willing to submit a PR? - -Yes / No (Help can be provided if you need assistance submitting a PR) +--- +name: Feature request +about: Ask for a new feature to be implemented in OpenAEV +title: 'feat: ' +labels: feature, needs triage +assignees: '' + +--- + +## Context + + + +## Use case + + + +## Current Workaround + + + +## Proposed Solution + + + +## Additional Information + + + +## If the feature request is approved, would you be willing to submit a PR? + +Yes / No (Help can be provided if you need assistance submitting a PR) diff --git a/.github/LABELS.md b/.github/LABELS.md new file mode 100644 index 00000000..9f7cdfe9 --- /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 00000000..c6f31e0b --- /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 00000000..4a0577c7 --- /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).