From 7181c05aaf3eb4f7e541f42f1dc463445f0e30ad Mon Sep 17 00:00:00 2001 From: Leonardo Grasso Date: Thu, 10 Aug 2023 18:15:24 +0200 Subject: [PATCH] docs(README.VERSION.md): clarify when internal version must not be bumped and general improvements Signed-off-by: Leonardo Grasso --- driver/README.VERSION.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/driver/README.VERSION.md b/driver/README.VERSION.md index 0bf065c327..b13bdbe54f 100644 --- a/driver/README.VERSION.md +++ b/driver/README.VERSION.md @@ -1,10 +1,16 @@ -# API version number +# Driver internal versioning -The file API_VERSION must contain a semver-like version number of the userspace<->kernel API. All other lines are ignored. +This document explains how and when the internal [*API version number*](#api-version-number) and the [*Schema version number*](#schema-version-number) must be incremented. They do not represent the driver version associated with a driver release. For more information about the driver version, see our [release process documentation](https://github.com/falcosecurity/libs/blob/master/release.md). -The version number must be incremented every time and only when a single change or an atomic group of changes - which meet the criteria described in the _When to Increment_ section below - is included in the `master` branch. Thus, a version bump can occur multiple times during the development and testing phases of a given release cycle. A given version bump must not group multiple changes that occurred sporadically during the release cycle. +The version numbers described below must be incremented every time and only when a single change or an atomic group of changes - which meet the criteria described in the relative _When to Increment_ section below - is included in the `master` branch. Thus, a version bump can occur multiple times during the development and testing phases of a given release cycle. A given version bump must not group multiple changes that occurred sporadically during the release cycle. -## When to increment +Please, do *not* increment these versions for patches that solely address build issues on specific kernels (for example, newly supported kernels) without impacting others. In these instances, only the driver's version number must be bumped when the driver is released. + +## API version number + +The first line of [API_VERSION](API_VERSION) file contains a semver-like version number of the **userspace<->kernel API**. All other lines are ignored. + +### When to increment **major version**: increment when the driver API becomes incompatible with previous userspace versions @@ -12,15 +18,11 @@ The version number must be incremented every time and only when a single change **patch version**: increment when code changes don't break compatibility (e.g. bug fixes) -Do *not* increment for patches that only add support for new kernels, without affecting already supported ones. - -# Schema version number - -The file SCHEMA_VERSION must contain a semver-like version number of the event schema. All other lines are ignored. +## Schema version number -The version number must be incremented every time and only when a single change or an atomic group of changes - which meet the criteria described in the _When to Increment_ section below - is included in the `master` branch. Thus, a version bump can occur multiple times during the development and testing phases of a given release cycle. A given version bump must not group multiple changes that occurred sporadically during the release cycle. +The first line of [SCHEMA_VERSION](SCHEMA_VERSION) file contains a semver-like version number of the **event schema**. All other lines are ignored. -## When to increment +### When to increment **major version**: increment when the schema becomes incompatible with previous userspace versions