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:
|
### 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.
intro
stratumis a monorepo with SRI low-level cratessv2-appsis a monorepo with SRI app-level cratesall crates across these two repositories have a well-defined dependency hierarchy (see #2192 for a visual representation via
mermaiddiagram)CONTRIBUTING.mdestablishes the main algorithm for version control:stratum/CONTRIBUTING.md
Lines 104 to 130 in a15c224
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.mdI 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.