release.md

Release Process

As per the Versioning and release process of the libs artifacts, this repository includes different components which are versioned (see the Driver SemVer and Versioning schema proposals) and released individually.

The two releases, which may occur either concurrently or independently of each other, are:

• The drivers release

  The drivers versioning process happens in this repository, but their release process is mainly automated and managed in our test-infra. Building is implemented there as per the Driverkit Build Grid, and drivers are published to https://download.falco.org/?prefix=driver/. Drivers distribution is implemented and maintained only to satisfy Falco's needs.

• The libs release (ie. libsinp and libscap)

  The libs versioning process happens in this repository. This release process is currently limited to the versioning only: and no artifacts are built nor distributed.

Commonly, we plan a release process when needed by Falco. In such cases, we usually release both drivers and libs versions simultaneously. Other releases may occur for hotfixes or at the discretion of maintainers. Releases are mainly used to signal points in time where the source code is assumed to be consistent and stable.

Completed releases are denoted by a git tag and a corresponding GitHub release.

Milestones

Releases are planned using GitHub milestones. The due date indicate when consumers should expected a tagged release.

Since we can know in advance the name of the following libs milestone, it will be set to a fixed name.
For driver, instead, we cannot know in advance the following release name, since it is dependent from API/SCHEMA version.
Therefore, we use a generic next-driver milestone that will be renamed to the correct name approaching the release.

Release team

The release team consists of a release manager and other contributors from the community. Usually, we seek volunteers during our community calls or in the #falco channel on Slack, and then decide together the release planning.

The release manager's responsibility is to coordinate the release process. The release manager will create a GitHub issue to track the progress and announce the release phases.

Note that the release manager does not need to be a maintainer. However, two maintainers with repository rights must be part of the team to approve PRs, do the git tags, manage GitHub milestones, etc.

Release Phases

Regardless if it is a driver or a libs release when initiating a new release, we follow a streamlined process inspired by the Kubernetes Release Phases.

Preparation

Approximately 4 weeks before the release due date, maintainers evaluate pending features and determine which features shall be integrated into the upcoming release based on a set of criteria, such as, but not limited to:

• Severity of the bug
• Type of feature (nice-to-have refactor vs adding significant new capabilities or improves stability or performance)
• Amount of user-facing changes
• Non user-facing changes that can affect resource utilization (CPU, memory usage ...)
• Amount of testing required to ensure stability and safety
• TODO: add more criteria

In this phase, all enhancements expected to go into the release should be merged before the code freeze.

Code freeze

Code freeze happens ~1 week before the release due date, and should last no more than ~5 days. Shorter freeze period are encouraged.

At this point, no new-feature PRs are allowed to be merged (exceptions apply).

Versioning rules must be double-checked and eventually enforced at this stage.

Release branch

During the code freeze period, a release branch is created once the release team ensures the code is in a good shape and reasonably no bugs are detected.

The naming convention for the release branch is release/M.m.x, where:

• M.m represents the Major and Minor version numbers of the release.
• x is simply the character 'x', indicating that the branch encompasses the entire M.m.x release series.

For processes that involve both drivers and libs releases, only the libs version number is reflected in the branch name.

When working with a release branch, adhere to the following rules:

• New commits should be added to the branch via cherry-picking.
• All tags within the release branch must maintain the same major and minor version as the release branch.
• Patch releases for the M.m.x series must be tagged directly within the respective release/M.m.x branch.
• If there's a need to bump the major or minor version (for either libs or drivers) after the release branch is created, a new release branch should be created for the relevant component with the corresponding version.

For example, a release/0.10.x is created; it will host tags 0.10.0, 0.10.1, 0.10.2 and so on. 0.10.1 will be made of some cherry picked commits on top of 0.10.0.
It will also host driver tags that are made within the same release cycle as the userspace part.

Once the release brach has been created:

• A PR must be opened in our test-infra repository to set the newly created branch as protected.

• A release candidate tag should be created in the release branch for testing purposes.

• Accurate testing is performed on the release candidate. Testing steps and criteria for passing each steps are outlined in [TBA doc]. It's highly recommended to use Falco as a consumer of the libs and drivers and perform automated and manual testing.

• If necessary, PRs may be exceptionally merged on the master branch (see the Exceptions section below) as a last resort to unblock a release. In such a case, relevant commits must be cherry-picked and ported to the release branch, and then a new release candidate is tagged.

• Not yet merged PRs must be moved to the subsequent milestone.

Thaw

Once maintainers are trustful that the release candidate is in good shape, or after ~5 days from the code freeze, we enter the Thaw phase.

From a technical perspective, this means that now the master and release branches diverge.

Release

After the thaw, it is time to git tag on the release branch the targeted version.
For libs tags, the release body gets autogenerated.
For drivers tags, the release body gets autogenerated; moreover kernel-tests get also ran against the tag, and their result matrixes attached to the release body.

From this point on:

• Only bug fix PRs are allowed to be merged in the release branch
  • if any, the version patch number must be bumped to git tag the release branch again.
• All kinds of PRs are allowed to be merged in the master branch again.

Exceptions

Exceptions are allowed for compelling reasons. Notably:

• During the code freeze phase, PRs might be exceptionally merged:
  • to complete already planned features for that milestone
  • to fix bugs in core features or that affect stability, safety, performance
  • to address broken functionalities (including the possibility of reverting the previous behavior)
  • improvements to the testing suite or the CI if necessary to unblock the release
• Hotfixes releases can happen anytime and without following the full process. In such cases, patches are merged into the relevant release branch (or a release branch is created if needed), then a new version is git tagged, and the hotfix is directly released.

Exceptions to the versioning rules are never allowed.

Versioning

Drivers versioning

The driver version number represents the build version of kernel-space drivers (i.e., the kernel module, the eBPF probe, and possibly any other kernel-space artifact).

Requirements

• The version MUST be a SemVer 2.0 compliant string.

• Since our driver APIs are assumed to be stable, the major version number MUST be equal to or greater than 1.

• The version string MUST be suffixed with +driver to distinguish it from libs version numbers.

• To pick a new driver version number:

  1. The API for user/kernel boundary is versioned in the source code. You MUST ensure the two files below have been updated by following the rules described in driver/README.VERSION.md:

     • driver/API_VERSION
     • driver/SCHEMA_VERSION

     If not, open a PR to fix them.

  2. Compute the driver version number by strictly following the Versioning Schema proposal's rules.

Note that API_VERSION and SCHEMA_VERSION are only used internally. On the other hand, only the driver version number will be used to tag a new release.

Libs versioning

The libs version number represents a software version of the user-space libraries (i.e., libscap, libsinsp, and possibly any other further user-space library), and it is not tied to the drivers version numbering.

Requirements

• The version MUST be a SemVer 2.0 compliant string.

• Since our userspace APIs are not yet stable, the major version number MUST be 0 (see the SemVer section about the initial development phase).

• The Plugin API is versioned in the code and follow a semver-like numbering scheme. If any changes have been made to the Plugin API since the last release, you MUST ensure the Plugin API version is updated accordingly. If not, open a PR to fix it.