Skip to content

Commit 77f42f1

Browse files
MikaayensonMikaayenson
authored
[FR] Add Versioning Processes to DR (#4223)
1 parent 6c2dad9 commit 77f42f1

File tree

9 files changed

+262
-6
lines changed

9 files changed

+262
-6
lines changed

‎.github/PULL_REQUEST_GUIDELINES/bug_guidelines.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,5 @@ These guidelines serve as a reminder set of considerations when addressing a bug
3131
- [ ] Ensure that the bug fix does not break existing functionality.
3232
- [ ] Review the bug fix with a peer or team member for additional insights.
3333
- [ ] Verify that the bug fix works across all relevant environments (e.g., different OS versions).
34-
- [ ] Confirm that all dependencies are up-to-date and compatible with the changes.
34+
- [ ] Confirm that all dependencies are up-to-date and compatible with the changes.
35+
- [ ] Confirm that the proper version label is applied to the PR `patch`, `minor`, `major`.

‎.github/PULL_REQUEST_GUIDELINES/enhancement_guidelines.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,4 @@ These guidelines serve as a reminder set of considerations when addressing addin
3232
- [ ] Review the enhancement with a peer or team member for additional insights.
3333
- [ ] Verify that the enhancement works across all relevant environments (e.g., different OS versions).
3434
- [ ] Confirm that all dependencies are up-to-date and compatible with the changes.
35+
- [ ] Confirm that the proper version label is applied to the PR `patch`, `minor`, `major`.

‎.github/PULL_REQUEST_GUIDELINES/hunt_tuning_guidelines.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,4 @@ These guidelines serve as a reminder set of considerations when tuning an existi
2727
- [ ] Evidence of testing and valid query usage.
2828
- [ ] Markdown Generated: Run `python -m hunting generate-markdown` with specific parameters to ensure a markdown version of the hunting TOML files is created.
2929
- [ ] Index Refreshed: Run `python -m hunting refresh-index` to refresh indexes.
30-
- [ ] Run Unit Tests: Run `pytest tests/test_hunt_data.py` to run unit tests.
30+
- [ ] Run Unit Tests: Run `pytest tests/test_hunt_data.py` to run unit tests.

‎.github/PULL_REQUEST_GUIDELINES/schema_enhancement_guidelines.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,5 @@ These guidelines serve as a reminder set of considerations when addressing addin
4343
- [ ] Implemented requisite downgrade functionality
4444
- [ ] Cross-referenced the feature with product documentation for consistency
4545
- [ ] Incorporated a comprehensive test rule in unit tests for full schema coverage
46-
- [ ] Conducted system testing, including fleet, import, and create APIs (e.g., run `make test-remote-cli`)
46+
- [ ] Conducted system testing, including fleet, import, and create APIs (e.g., run `make test-remote-cli`)
47+
- [ ] Confirm that the proper version label is applied to the PR `patch`, `minor`, `major`.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ from your submission, but they are here to help bring them to your attention.
3636

3737
<!-- Delete any items that are not applicable to this PR. -->
3838

39-
- [ ] Added a label for the type of pr: `bug`, `enhancement`, `schema`, `Rule: New`, `Rule: Deprecation`, `Rule: Tuning`, `Hunt: New`, or `Hunt: Tuning` so guidelines can be generated
39+
- [ ] Added a label for the type of pr: `bug`, `enhancement`, `schema`, `maintenance`, `Rule: New`, `Rule: Deprecation`, `Rule: Tuning`, `Hunt: New`, or `Hunt: Tuning` so guidelines can be generated
4040
- [ ] Added the `meta:rapid-merge` label if planning to merge within 24 hours
4141
- [ ] Secret and sensitive material has been managed correctly
4242
- [ ] Automated testing was updated or added to match the most common scenarios

‎.github/release-drafter.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name-template: 'v$RESOLVED_VERSION'
2+
tag-template: 'v$RESOLVED_VERSION'
3+
categories:
4+
- title: 🚀 Features
5+
label: 'enhancement'
6+
- title: 🐛 Bug Fixes
7+
label: 'bug'
8+
- title: 🛠 Internal Changes
9+
labels:
10+
- 'maintenance'
11+
- 'schema'
12+
- 'documentation'
13+
- 'python'
14+
- title: 🔍 Hunting Updates
15+
label: 'Hunting'
16+
change-template: '- $TITLE (#$NUMBER) @$AUTHOR'
17+
exclude-labels:
18+
- 'skip-changelog'
19+
version-resolver:
20+
major:
21+
labels:
22+
- 'major'
23+
minor:
24+
labels:
25+
- 'minor'
26+
patch:
27+
labels:
28+
- 'patch'
29+
default: patch
30+
template: |
31+
## Changes
32+
$CHANGES

‎.github/workflows/version-code-and-release.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Version Code Check and Draft Release
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'lib/**'
7+
- 'hunting/**/*.py'
8+
- 'pyproject.toml'
9+
- 'Makefile'
10+
- 'docs/**'
11+
- 'detection_rules/**'
12+
- 'tests/**'
13+
- '**/*.md'
14+
types: [opened, reopened, synchronize]
15+
push:
16+
branches:
17+
- main
18+
paths:
19+
- 'pyproject.toml'
20+
21+
permissions:
22+
contents: read
23+
pull-requests: read
24+
25+
jobs:
26+
label_check:
27+
if: github.event_name == 'pull_request'
28+
runs-on: ubuntu-latest
29+
steps:
30+
- name: Ensure PR has Version Bump Label
31+
uses: actions/github-script@v6
32+
with:
33+
github-token: ${{ secrets.GITHUB_TOKEN }}
34+
script: |
35+
const labels = ['major', 'minor', 'patch'];
36+
const prLabels = context.payload.pull_request.labels.map(label => label.name);
37+
const hasVersionLabel = labels.some(label => prLabels.includes(label));
38+
if (!hasVersionLabel) {
39+
throw new Error("PR must have one of the following labels: major, minor, or patch.");
40+
}
41+
42+
version_check:
43+
if: github.event_name == 'pull_request'
44+
needs: label_check
45+
runs-on: ubuntu-latest
46+
steps:
47+
- name: Checkout repository
48+
uses: actions/checkout@v4
49+
with:
50+
fetch-depth: 0
51+
52+
- name: Check if core pyproject.toml was updated
53+
run: |
54+
BASE_COMMIT="${{ github.event.pull_request.base.sha }}"
55+
56+
if ! git diff --name-only "$BASE_COMMIT" "$GITHUB_SHA" | grep '^pyproject.toml$'; then
57+
echo "Code changes detected in core, but pyproject.toml was not updated."
58+
exit 1
59+
fi
60+
61+
- name: Check if lib pyproject.toml files were updated
62+
run: |
63+
BASE_COMMIT="${{ github.event.pull_request.base.sha }}"
64+
65+
if git diff --name-only "$BASE_COMMIT" "$GITHUB_SHA" | grep -E 'lib/kql/|lib/kibana/'; then
66+
if ! git diff --name-only "$BASE_COMMIT" "$GITHUB_SHA" | grep -E 'lib/kql/pyproject.toml|lib/kibana/pyproject.toml'; then
67+
echo "Changes detected in kql or kibana library, but respective pyproject.toml was not updated."
68+
exit 1
69+
fi
70+
fi
71+
72+
release_drafter:
73+
if: github.ref == 'refs/heads/main'
74+
runs-on: ubuntu-latest
75+
permissions:
76+
contents: write
77+
steps:
78+
- name: Checkout repository
79+
uses: actions/checkout@v4
80+
81+
- name: Run Release Drafter
82+
uses: release-drafter/release-drafter@v6
83+
with:
84+
config-name: release-drafter.yml
85+
env:
86+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎docs/versioning.md‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Supported Versions and Releases
1+
# Rule Supported Versions and Releases
22

33
This document provides detailed information about the different versions that are supported and released for prebuilt detection rules.
44

@@ -24,3 +24,138 @@ The following version(s) are maintained along with the current version.
2424
## End of Life Policy
2525

2626
Our policy is to support and provide public releases for `Current`, `Current-1`, `Current-2`, `Current-3` versions. We maintain and do not release `Current-4` and `Current-5` versions.
27+
28+
29+
# Code Supported Versions and Releases
30+
31+
This outlines the versioning strategy and release process for the [detection-rules](https://github.com/elastic/detection-rules) repository, covering the core code, `kql` and `kibana` libraries, configuration files, and the `hunting` folder. The strategy follows semantic versioning to ensure clear communication of changes to users and compatibility with different Elastic Stack versions.
32+
33+
> [!IMPORTANT]
34+
> This versioning process **excludes** the detection rules themselves. Detection rules are released separately and are not tied to the following process.
35+
36+
---
37+
38+
## Versioning Strategy
39+
40+
### Components Covered by Versioning:
41+
- **Core Detection-Rules Code**: Handles logic for rule management, CLI, etc.
42+
- **Libraries**:
43+
- **`kql`**: Manages Kibana Query Language parsing and operations.
44+
- **`kibana`**: Handles integrations and API interactions with Kibana.
45+
- **Configuration Files**: Under the `etc/` folder that impact schema and DAC.
46+
- **Hunting Logic**: The `hunting/` folder, which manages hunting rules.
47+
48+
49+
### Semantic Versioning Approach:
50+
We will use **Semantic Versioning** with the format `MAJOR.MINOR.PATCH`:
51+
- **MAJOR version (`X.0.0`)**: For backward-incompatible changes.
52+
- **MINOR version (`0.Y.0`)**: For backward-compatible new features.
53+
- **PATCH version (`0.0.Z`)**: For backward-compatible bug fixes or small improvements.
54+
55+
> [!NOTE]
56+
> The GitHub labels `patch`, `minor`, or `major` will be used in PRs to indicate the type of change being made.
57+
58+
---
59+
60+
## Versioning Guidelines
61+
62+
### Patch Version (`0.0.Z`):
63+
Increment the patch version when making bug fixes, performance improvements, or small enhancements that do not break backward compatibility. Open a PR to ensure the proper `pyproject.toml` files and any other `version` related files are bumped.
64+
65+
<details><summary>Expand for Examples</summary>
66+
<p>
67+
68+
**Examples**:
69+
- **Kibana Library**:
70+
- Minor fixes to API calls to ensure correct data retrieval.
71+
- Updates to the `kibana` lib without adding new features.
72+
- **KQL Library**:
73+
- Small bug fixes in the query parsing logic.
74+
- Optimizations that don't alter functionality.
75+
- **Core Detection-Rules Code**:
76+
- Fixes for CLI bugs or performance tweaks.
77+
- Minor enhancements to rule management that don’t require users to change workflows.
78+
- **Hunting Folder**:
79+
- Bug fixes in hunting rules logic.
80+
- Small performance tweaks for the hunting rule management.
81+
- **Docs Folder**:
82+
- Updates to documentation.
83+
84+
</p>
85+
</details>
86+
87+
---
88+
89+
### Minor Version (`0.Y.0`):
90+
Increment the minor version when adding backward-compatible new features, enhancements, or functionality.
91+
92+
<details><summary>Expand for Examples</summary>
93+
<p>
94+
95+
**Examples**:
96+
- **Kibana Library**:
97+
- Adding a new API endpoint to interact with Elastic Kibana X.Y while maintaining backward compatibility with older versions.
98+
- **KQL Library**:
99+
- Adding new query parsing functionality that is backward-compatible with previous Elastic Stack versions.
100+
- **Core Detection-Rules Code**:
101+
- New CLI commands or functionality for managing detection rules.
102+
- New optional fields in rule schemas that have minimum compatibility requirements. (e.g adding `alert_suppression` with `min_compat=8.14`).
103+
- **Hunting Folder**:
104+
- Adding new hunting rule management features that are optional and backward-compatible.
105+
- Enhancements in generating hunting rule markdown or CLI features.
106+
107+
</p>
108+
</details>
109+
110+
> [!NOTE]
111+
> When bumping this version, the patch version should be reset to `0` and the major version should remain the same.
112+
113+
---
114+
115+
### Major Version (`X.0.0`):
116+
Increment the major version when introducing backward-incompatible changes that require users to update workflows, Elastic Stack versions, or rule management strategies.
117+
118+
<details><summary>Expand for Examples</summary>
119+
<p>
120+
121+
**Examples**:
122+
- **Kibana Library**:
123+
- Replacing or removing an existing API endpoint that forces users to upgrade to Elastic X.Y
124+
- **KQL Library**:
125+
- Structural changes to query parsing logic that break compatibility with previous Elastic Stack versions.
126+
- **Core Detection-Rules Code**:
127+
- Breaking changes to rule schema definitions or CLI workflows that require user updates.
128+
- Forcing users to migrate to a newer Elastic Stack version due to changes in core code or schema compatibility.
129+
- **Hunting Folder**:
130+
- Major refactors of the hunting logic that break existing workflows.
131+
- Changes to how hunting rules are defined or managed, requiring users to adjust configurations.
132+
133+
</p>
134+
</details>
135+
136+
> [!NOTE]
137+
> When bumping this version, the minor version and patch version should be reset to `0`.
138+
139+
---
140+
141+
## Tagging Process
142+
143+
Each release will be tagged using the following format:
144+
- **Tag Format**: `vX.Y.Z` (e.g., `v1.2.0`).
145+
- **Single Tag for Combined Releases**: If there are changes to the core detection-rules code or libraries (`kql`, `kibana`), they will be tagged together as a single release with the core detection-rules versioning.
146+
- **Hunting Folder**: Changes to the hunting logic will be included in the combined release.
147+
148+
> [!CAUTION]
149+
> When a version is bumped in a lib, we need to also bump the core `pyproject.toml` file *(e.g A version bump in `kql` will also require a similar version bump in the core detection-rules versioning)*.
150+
---
151+
152+
## When to Trigger a GitHub Release
153+
154+
A draft release will be triggered in the following cases:
155+
- **New Feature or Bug Fix**: Once a feature or bug fix is merged into `main`, a version bump is made according to the semantic versioning rules.
156+
- **Version Bump**: After the version bump, a GitHub release will be created using **release-drafter** CI workflow to automate draft release generation.
157+
158+
As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish quarterly.
159+
160+
> [!IMPORTANT]
161+
> Proper PR labels need to be added for this to properly be labeled and added to the draft.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "detection_rules"
3-
version = "0.1.0"
3+
version = "0.2.0"
44
description = "Detection Rules is the home for rules used by Elastic Security. This repository is used for the development, maintenance, testing, validation, and release of rules for Elastic Security’s Detection Engine."
55
readme = "README.md"
66
requires-python = ">=3.12"

0 commit comments

Comments
 (0)