Skip to content

enforce versioning rules via CI #2191

Description

@plebhash

intro

  • stratum is a monorepo with SRI low-level crates
  • sv2-apps is a monorepo with SRI app-level crates

all crates across these two repositories have a well-defined dependency hierarchy (see #2192 for a visual representation via mermaid diagram)

CONTRIBUTING.md establishes the main algorithm for version control:

stratum/CONTRIBUTING.md

Lines 104 to 130 in a15c224

### Versioning and public dependencies
Whenever submitting a PR that modifies some crate, it's up to the contributor to make sure the versioning of this crate remains sane. The main factors to take into account are:
1. According to SemVer 2.0.0 and the modifications on this PR, what kind of version bump does this crate deserve?
2. Avoiding redundant version bumps:
- Has the version of crate already been bumped on this repo since it was last published to crates.io?
- If yes, do the changes introduced by this PR require a larger bump than the one already made?
3. Keeping sanity across dependency chains:
- Which other crates on this repo depend on this crate?
- Amongst them, are there types from this crate exposed on their public APIs?
Factors 1 and 2 are partially enforced via CI (but enforcement via PR review is still encouraged). Factor 3 must be fully enforced via PR reviews.
Factor 2 is about avoiding redundant version bumps. Since crates are only published to crates.io periodically (during global release), maybe other PRs already bumped this crate version.
Factor 3 is about keeping sanity across dependency chains. If a crate only uses a dependency internally, updating that dependency does not automatically require an incompatible version bump for the dependent crate. However, if a dependency appears in the dependent crate's public API, then changing that dependency to an incompatible version also changes the dependent crate's public API.
Public API exposure includes, but is not limited to:
- re-exports;
- public function or method arguments and return types;
- public trait method signatures;
- public enum variant payloads;
- public struct fields;
- public type aliases and associated types.
For crates that are already `1.0.0` or above, an incompatible version bump means a MAJOR bump. For `0.x.y` crates, an incompatible version bump usually means a MINOR bump, for example `0.2.3 -> 0.3.0`. A PATCH bump on a `0.x.y` crate is still treated as compatible within the same minor line, for example `0.2.3 -> 0.2.4`.

unfortunately, this algorithm is non-trivial and invites human-error.

proposal

as discussed in #2187 (comment), I propose we create a shell script that enforces the rules established on CONTRIBUTING.md

I should clarify that I'm not pushing for us to remove human responsability from the loop here. Ultimately, PR author is responsible for making sure their contribution abides by repo rules.

but I think we are at a place where we could confidently enforce these rules via github CI.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ci/cdCI/CDversion-bumpversion bump for release management

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status
    Todo 📝
    Status
    Todo 📝

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions