# Rule Supported Versions and Releases This document provides detailed information about the different versions that are supported and released for prebuilt detection rules. ## Current Version The current version of prebuilt detection rules is `v8.15`. ## Previous Versions Released The following version(s) are released along with the current version. - `v8.14` - `v8.13` - `v8.12` ### Previous Versions Maintained The following version(s) are maintained along with the current version. - `v8.11` - `v8.10` ## End of Life Policy 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. # Code Supported Versions and Releases 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. > [!IMPORTANT] > This versioning process **excludes** the detection rules themselves. Detection rules are released separately and are not tied to the following process. --- ## Versioning Strategy ### Components Covered by Versioning: - **Core Detection-Rules Code**: Handles logic for rule management, CLI, etc. - **Libraries**: - **`kql`**: Manages Kibana Query Language parsing and operations. - **`kibana`**: Handles integrations and API interactions with Kibana. - **Configuration Files**: Under the `etc/` folder that impact schema and DAC. - **Hunting Logic**: The `hunting/` folder, which manages hunting rules. ### Semantic Versioning Approach: We will use **Semantic Versioning** with the format `MAJOR.MINOR.PATCH`: - **MAJOR version (`X.0.0`)**: For backward-incompatible changes. - **MINOR version (`0.Y.0`)**: For backward-compatible new features. - **PATCH version (`0.0.Z`)**: For backward-compatible bug fixes or small improvements. > [!NOTE] > The GitHub labels `patch`, `minor`, or `major` will be used in PRs to indicate the type of change being made. --- ## Versioning Guidelines ### Patch Version (`0.0.Z`): 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.
Expand for Examples

**Examples**: - **Kibana Library**: - Minor fixes to API calls to ensure correct data retrieval. - Updates to the `kibana` lib without adding new features. - **KQL Library**: - Small bug fixes in the query parsing logic. - Optimizations that don't alter functionality. - **Core Detection-Rules Code**: - Fixes for CLI bugs or performance tweaks. - Minor enhancements to rule management that don’t require users to change workflows. - **Hunting Folder**: - Bug fixes in hunting rules logic. - Small performance tweaks for the hunting rule management. - **Docs Folder**: - Updates to documentation.

--- ### Minor Version (`0.Y.0`): Increment the minor version when adding backward-compatible new features, enhancements, or functionality.
Expand for Examples

**Examples**: - **Kibana Library**: - Adding a new API endpoint to interact with Elastic Kibana X.Y while maintaining backward compatibility with older versions. - **KQL Library**: - Adding new query parsing functionality that is backward-compatible with previous Elastic Stack versions. - **Core Detection-Rules Code**: - New CLI commands or functionality for managing detection rules. - New optional fields in rule schemas that have minimum compatibility requirements. (e.g adding `alert_suppression` with `min_compat=8.14`). - **Hunting Folder**: - Adding new hunting rule management features that are optional and backward-compatible. - Enhancements in generating hunting rule markdown or CLI features.

> [!NOTE] > When bumping this version, the patch version should be reset to `0` and the major version should remain the same. --- ### Major Version (`X.0.0`): Increment the major version when introducing backward-incompatible changes that require users to update workflows, Elastic Stack versions, or rule management strategies.
Expand for Examples

**Examples**: - **Kibana Library**: - Replacing or removing an existing API endpoint that forces users to upgrade to Elastic X.Y - **KQL Library**: - Structural changes to query parsing logic that break compatibility with previous Elastic Stack versions. - **Core Detection-Rules Code**: - Breaking changes to rule schema definitions or CLI workflows that require user updates. - Forcing users to migrate to a newer Elastic Stack version due to changes in core code or schema compatibility. - **Hunting Folder**: - Major refactors of the hunting logic that break existing workflows. - Changes to how hunting rules are defined or managed, requiring users to adjust configurations.

> [!NOTE] > When bumping this version, the minor version and patch version should be reset to `0`. --- ## Tagging Process Each release will be tagged using the following format: - **Tag Format**: `dev-vX.Y.Z` (e.g., `dev-v1.2.0`). - **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. - **Hunting Folder**: Changes to the hunting logic will be included in the combined release. > [!CAUTION] > 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)*. --- ## When to Trigger a GitHub Release A draft release will be triggered in the following cases: - **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. - **Version Bump**: After the version bump, a GitHub release will be created using **release-drafter** CI workflow to automate draft release generation. As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish quarterly. > [!IMPORTANT] > Proper PR labels need to be added for this to properly be labeled and added to the draft.