Skip to content

Commit 39c98a9

Browse files
MikaayensonMikaayenson
committed
[FR] Add Versioning Processes to DR
1 parent b6847c7 commit 39c98a9

File tree

3 files changed

+207
-1
lines changed

3 files changed

+207
-1
lines changed

‎.github/release-drafter.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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+
label: 'internal'
10+
- title: 🔍 Hunting Updates
11+
label: 'hunting'
12+
change-template: '- $TITLE (#$NUMBER) @$AUTHOR'
13+
exclude-labels:
14+
- 'skip-changelog'
15+
template: |
16+
## Changes
17+
$CHANGES

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Version Code Check and Draft Release
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'lib/kql/**'
7+
- 'lib/kibana/**'
8+
- 'hunting/**'
9+
- 'etc/**'
10+
- 'pyproject.toml'
11+
types: [opened, reopened, synchronize]
12+
push:
13+
branches:
14+
- main
15+
16+
permissions:
17+
contents: write
18+
pull-requests: write
19+
20+
jobs:
21+
version_check:
22+
runs-on: ubuntu-latest
23+
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@v4
27+
28+
- name: Check for changes in kql, kibana, hunting, and etc
29+
id: check_changes
30+
run: |
31+
CHANGED_FILES=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep -E 'lib/kql|lib/kibana|detection_rules|tests|hunting|etc/' || echo "no-changes")
32+
if [ "$CHANGED_FILES" != "no-changes" ]; then
33+
echo "CHANGES_FOUND=true" >> $GITHUB_ENV
34+
else
35+
echo "CHANGES_FOUND=false" >> $GITHUB_ENV
36+
fi
37+
38+
- name: Fail if no version bump in pyproject.toml
39+
if: env.CHANGES_FOUND == 'true'
40+
run: |
41+
if ! git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep 'pyproject.toml'; then
42+
echo "Code changes detected in but core pyproject.toml was not updated."
43+
exit 1
44+
fi
45+
46+
release_drafter:
47+
needs: version_check
48+
runs-on: ubuntu-latest
49+
50+
steps:
51+
- name: Checkout repository
52+
uses: actions/checkout@v4
53+
54+
- name: Run Release Drafter
55+
uses: release-drafter/release-drafter@v6
56+
with:
57+
config-name: release-drafter.yml
58+
env:
59+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎docs/versioning.md‎

Lines changed: 131 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,133 @@ 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+
---
56+
57+
## Versioning Guidelines
58+
59+
### Patch Version (`0.0.Z`):
60+
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.
61+
62+
<details><summary>Expand for Examples</summary>
63+
<p>
64+
65+
**Examples**:
66+
- **Kibana Library**:
67+
- Minor fixes to API calls to ensure correct data retrieval.
68+
- Updates to the `kibana` lib without adding new features.
69+
- **KQL Library**:
70+
- Small bug fixes in the query parsing logic.
71+
- Optimizations that don't alter functionality.
72+
- **Core Detection-Rules Code**:
73+
- Fixes for CLI bugs or performance tweaks.
74+
- Minor enhancements to rule management that don’t require users to change workflows.
75+
- **Hunting Folder**:
76+
- Bug fixes in hunting rules logic.
77+
- Small performance tweaks for the hunting rule management.
78+
79+
</p>
80+
</details>
81+
82+
---
83+
84+
### Minor Version (`0.Y.0`):
85+
Increment the minor version when adding backward-compatible new features, enhancements, or functionality.
86+
87+
<details><summary>Expand for Examples</summary>
88+
<p>
89+
90+
**Examples**:
91+
- **Kibana Library**:
92+
- Adding a new API endpoint to interact with Elastic Kibana X.Y while maintaining backward compatibility with older versions.
93+
- **KQL Library**:
94+
- Adding new query parsing functionality that is backward-compatible with previous Elastic Stack versions.
95+
- **Core Detection-Rules Code**:
96+
- New CLI commands or functionality for managing detection rules.
97+
- New optional fields in rule schemas that have minimum compatibility requirements. (e.g adding `alert_suppression` with `min_compat=8.14`).
98+
- **Hunting Folder**:
99+
- Adding new hunting rule management features that are optional and backward-compatible.
100+
- Enhancements in generating hunting rule markdown or CLI features.
101+
102+
</p>
103+
</details>
104+
105+
> [!NOTE]
106+
> When bumping this version, the patch version should be reset to `0` and the major version should remain the same.
107+
108+
---
109+
110+
### Major Version (`X.0.0`):
111+
Increment the major version when introducing backward-incompatible changes that require users to update workflows, Elastic Stack versions, or rule management strategies.
112+
113+
<details><summary>Expand for Examples</summary>
114+
<p>
115+
116+
**Examples**:
117+
- **Kibana Library**:
118+
- Replacing or removing an existing API endpoint that forces users to upgrade to Elastic X.Y
119+
- **KQL Library**:
120+
- Structural changes to query parsing logic that break compatibility with previous Elastic Stack versions.
121+
- **Core Detection-Rules Code**:
122+
- Breaking changes to rule schema definitions or CLI workflows that require user updates.
123+
- Forcing users to migrate to a newer Elastic Stack version due to changes in core code or schema compatibility.
124+
- **Hunting Folder**:
125+
- Major refactors of the hunting logic that break existing workflows.
126+
- Changes to how hunting rules are defined or managed, requiring users to adjust configurations.
127+
128+
</p>
129+
</details>
130+
131+
> [!NOTE]
132+
> When bumping this version, the minor version and patch version should be reset to `0`.
133+
134+
---
135+
136+
## Tagging Process
137+
138+
Each release will be tagged using the following format:
139+
- **Tag Format**: `vX.Y.Z` (e.g., `v1.2.0`).
140+
- **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.
141+
- **Hunting Folder**: Changes to the hunting logic will be included in the combined release.
142+
143+
> [!CAUTION]
144+
> 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)*.
145+
---
146+
147+
## When to Trigger a GitHub Release
148+
149+
A draft release will be triggered in the following cases:
150+
- **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.
151+
- **Version Bump**: After the version bump, a GitHub release will be created using **release-drafter** CI workflow to automate draft release generation.
152+
153+
As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish quarterly.
154+
155+
> [!IMPORTANT]
156+
> Proper PR labels need to be added for this to properly be labeled and added to the draft.

0 commit comments

Comments
 (0)