docs/dev-proc/versioning.md: versioning guidelines RFC

[macpijan]

No description provided.

[pietrushnic]

@macpijan I feel it partially clashes with semantic and DES versioning. In the case of DES, we increase patch version with multiple new features. I like above division, but how to align that with DES versioning, or how to change DES versioning to satisfy your needs and DES/Dasharo Community Release needs?

[miczyg1]

Patch version could be for both features and fixes. Some time ago my idea was to make minor version indicate backwards incompatibility resulting in flashing full image or BIOS region.

[macpijan]

@pietrushnic

I feel it partially clashes with semantic

How it clashes with:

    MAJOR version when you make incompatible API changes
    MINOR version when you add functionality in a backward compatible manner
    PATCH version when you make backward compatible bug fixes

We link to semver and claim to use it, but never have.

[macpijan]

Some time ago my idea was to make minor version indicate backwards incompatibility resulting in flashing full image or BIOS region.

It is also already in conflict with: https://docs.dasharo.com/dev-proc/versioning/#dasharo-community-releases

[pietrushnic]

We link to semver and claim to use it, but never have.

The question is why?

We can have a discussion about interleaving assumptions about versioning, but IMHO, this is a waste of time because of reasons which were already discussed (not used semver, lack of compatibility with our other claims about versioning). The problem is proposing a versioning scheme that will work for all options. The above proposal does not consider previous assumptions. Even abandoning or modifying those cannot be accepted, IMHO.

Maybe something like this would address most of the problems? Please note that in relation to semver changing from using to adhering.

Dasharo Versioning Scheme

Dasharo adheres to Semantic Versioning and utilizes the Keep A Changelog framework to document the changes introduced in each new release.

The versioning structure is defined as follows:

• MAJOR version (X.y.z)

  • Significant changes in the firmware update method.
  • Changes that require different flashing procedures compared to previous releases.

• MINOR version (x.Y.z)

  • The introduction of at least one new feature.
  • Applicable to both Dasharo Entry Subscription Releases and Dasharo Community Releases.

• PATCH version (x.y.Z)

  • Includes only fixes, with no new features introduced.
  • Primarily for Dasharo Entry Subscription Releases.

Initial Development Phase (0.y.z)

• Reserved for initial development or the first release.
• May not fulfill all Dasharo Quality Criteria.

Mapping Dasharo Versions

• Dasharo versions correlate with the details mentioned in the release notes.
• Find the release notes for your hardware platform under the respective section in the menu (Supported Hardware → Hardware Model → Releases).

Dasharo releases fall into two categories:

1. Dasharo Entry Subscription Releases
2. Dasharo Community Releases

Dasharo Entry Subscription Releases

Subscribers receive firmware updates more frequently compared to the community releases. The frequency of updates is contingent upon the number of subscriptions sold and other funding avenues. However, it guarantees no less than two updates per year.

• Version Characteristic: Changing patch version (z).
• Benefits: Early access to the latest features and fixes.
• Subscription Details: Find out how to subscribe here.

Dasharo Community Releases

Community releases occur annually, incorporating all the features and fixes introduced in the Entry Subscription Releases over the year.

• Version Characteristic: Zero patch version (x.y.0) with a changing minor version (y).
• Update Notifications: Subscribe to the free mailing list for your hardware platform to stay updated. Find the link in the menu (Supported Hardware → Hardware Model → Releases).

[pietrushnic]

Semantic Versioning: Strict semantic versioning does not include the "v" prefix in the version number.

[miczyg1]

Semantic Versioning: Strict semantic versioning does not include the "v" prefix in the version number.

Ohh I recall arguing about it, that we should not include v prefix

[miczyg1]

I wanted to use the major version for Dasharo v2 (which would keep all board on a single branch).

[macpijan]

In that way we leave bumping MAJOR to our arbitrary decision when we fell it's time (e.g. some technical goals are met).
This is also fine for me, as long as we apply something like: https://github.com/Dasharo/docs/pull/655/files#r1326944982