docs: enforce bumping driver api and schema versions at every change

[jasondellaluce]

What type of PR is this?

/kind design

/kind documentation

Any specific area of the project related to this PR?

/area API-version

/area CI

Does this PR require a change in the driver versions?

What this PR does / why we need it:

We have release and versioning policies that regulate how versions should progress for driver, driver API, and driver schema. However, we don't have anything specific in place as for when a given version should be bumped.

As such, up until now we bumped these the driver API and schema numbers by following good sense, and generally by doing it at least once per release cycle. However, given that the libs are a common codebase shared across many forks and clients, this non-strict practice can be dangerous for whoever attaches to some dev commit containing a new API/schema change, but also having a version number not aligned with it. Example scenario:

• Schema version is vX.Y.Z
• We merge a PR in mainline adding a new event to the events table
• We skip bumping the schema version, because we already did it for this release cycle of the libs
• A client pins the falcosecurity/libs dependency to the latest HEAD commit of mainline (with all the due risks, note: this proposal doesn't provide any novel guarantee that mainline is functionally stable)
• The client is not able to capture the presence of the new event in the events table by relying on the schema version number, because vX.Y.Z represents both the presence and the absence of that event in mainline

As such, this PR acts as a proposal for making version bumping mandatory at every single change or atomic group of changes (e.g. a merged PR) for both the driver API and schema numbers. This can have the direct cause that these numbers grow by more than one major/minor version between two subsequent libs/driver releases, however the benefit is that the mainline will always be consistent with respect to the changes in the drivers and the given version numbers representing them.

Of course, automation for this is very helpful but not trivial. For the API version, I suspect we can't do anything smarter than what we already do if not holding the PR preventively. For the schema version (which luckily changes more frequently), we can enforce an automated check.

Which issue(s) this PR fixes:

Special notes for your reviewer:

cc @falcosecurity/libs-maintainers

Does this PR introduce a user-facing change?:

NONE

[jasondellaluce]

Example of failure message in workflow: https://github.com/falcosecurity/libs/actions/runs/5729825596/job/15527358945?pr=1273

[FedeDP]

So, are we just failing the check? Without any comment nor further notice to the user?

[FedeDP]

I mean, i don't like the fact that the API_VERSION check is posting a comment, while this check is going to fail.

[jasondellaluce]

IMO a comment is useful when we have a non-failing silent warning, because nobody would read the message if it was simply logged in a successful CI job. On the other hand here we're turning it into an actual check that can lead to either a failure be skipped, meaning that the output is clearly visibile by everyone. In case the job fails, reviewers and contributors can check the message and understand that versioning is the issue.

As for consistency, I agree with you that it's ugly to have two different approaches. But for a matter of purpose, I think this makes sense. I'm not gonna fight for this though, it's just my opinion and I'm open to change.

[FedeDP]

I mean, what if i just add a comment to driver/event_table?
Would i need to forcefully bump the SCHEMA_VERSION just to silence the CI check?

[jasondellaluce]

For this reason, my proposal would be to make the check non-required.

[leogr]

SGMT! And I totally agree with the intent of this proposal. Thank you!

I just suggest a minor clarification (see below)

[FedeDP]

Much better IMHO :)
/approve

[poiana]

LGTM label has been added.

Git tree hash: ecf4c92c3de462b82b0ca74cd15e18344ba4e8c9

[jasondellaluce]

Thanks everyone! I pushed a version bump for the schema version to 2.7.0 to include the latest #1270 from @therealbobo in which it was omitted.

[FedeDP]

/approve

[poiana]

LGTM label has been added.

Git tree hash: 0a5d3428851b0e34d7be356d459e8b077606a7dd

[incertum]

/approve

[poiana]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: FedeDP, incertum, jasondellaluce

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [FedeDP,incertum,jasondellaluce]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment