A draft for a stability guide #171

Byron · 2021-08-24T04:14:18Z

It's goal is to explain what crate and application users can expect in terms of stability.

Having it should help building trust and encourage more people to rely on the crates provided
here.

~~pin all intra-workspace dependencies to their specific version while in pre-release mode~~
- This allows us to have breaking changes in crate A with a minor version change while only bumping the patch level of B which uses A, without breaking C which uses B and A as long as C also pins A and B.
- But it's probably not worth protecting against that outside of ALPHA releases as this also means upgrades for patch levels don't happen automatically.
~~make cargo smart-release handle changing pinned versions when bumping versions~~
~~introduce git-ref-base as foundation crate~~ make git-ref available.
cargo smart-release shouldn't have to use unstable git-repository
which crates would be eligble to a first release? I am looking at git-lock and git-tempflie - to practice ST2 at least.
Sort out how to handle omnipresent primitive types, like git-hash::ObjectId
- it's ST1 now
What about the bstr crate? Do we ultimately have to remove it from the API?
- A 1.0 release is planned

…which lacks a lot of explanation. It uses monodrap to for nice structural diagrams, see https://monodraw.helftone.com for more.

kim · 2021-08-24T05:55:28Z

Do you also have a MSRV policy?

…and add notes to some support `cargo smart-release` will have to provide. Also don't let it kill build-metadata for no reason, for now.

…but allow such access behind a feature gate. That way gitoxide-core can be the canary for such a feature and also help measure when git-repository is probably ready for a stable release as there is no more unstable crates required, everything can go through the Easy API.

Byron · 2021-08-24T08:15:50Z

Great catch! My intuition is to require the latest stable release by default until ST1 is reached by at least one application crate. From there the MSRV can be updated to whatever is current during the next release IF there are any benefits to do so.

What do you think about that? I think it should also be mentioned that the stability guide isn't stable in itself and it can be adjusted if better ways are discovered.

Edit: Also: Is changing the MSRV a breaking change in itself?

kim · 2021-08-24T09:10:21Z

SGTM. I think it's more of a "good to know" at this stage :)

Let's keep it very simple for now and allow ourselves to keep up to date with stable. That way we get to use the latest clippy which is really the selling point right now.

Byron · 2021-08-24T13:36:14Z

Great, while writing it down I changed the MSRV back to: Let's use the latest stable to keep it simple, but be open to requirements to keep the Rustc version stable for a while or reduce it to a given version.

What I wrote down makes sense to me and seems good enough for a first iteration. It's definitely good to have an outlook and a vision. One thing is for sure: for ST2 and ST1 having some additional tooling support would be great to be sure embargos are considered during these mostly automatic releases 😅.

…now it's a thing!

Byron · 2021-08-24T13:41:18Z

@avoidscorn @edward-shen @joshtriplett It would be great if you could take a look and see if something important was missed in this first draft of the stability guide. Thanks a lot.

edward-shen · 2021-08-24T16:21:54Z

STABILITY.md

+### Tier 3: pre-release crates
+
+Pre-release crates is marked with major version number zero, for example `0.1.4` and lives in stability tier 3 _(->ST3)_.
+
+It's acceptable to let each breaking change be followed by a minor version release.
+Dependent crates are advised to use `=<version>` version requirements to avoid automatic updates of patch levels which
+may be breaking if they also depend on other `plumbing crates`.


Is this necessary? This is implied by semver, and fwiw is the convention in Rust's ecosystem for pre 1.0 crates anyways.

I think it's beneficial to spell out how this is handled even if it represents the status quo.

Also I find helpful to explicitly state that dependents should pin their dependencies for stability. For the latter to truly work gitoxide crates should also pin their dependencies, so that A-0.4 -> B 0.3 won't have a chance to break downstream if A-0.4.1 -> B -> 0.4 is released with dependent D using A (which auto-updates) and B 0.3, which won't auto-update.

Also I find helpful to explicitly state that dependents should pin their dependencies for stability. For the latter to truly work gitoxide crates should also pin their dependencies, so that A-0.4 -> B 0.3 won't have a chance to break downstream if A-0.4.1 -> B -> 0.4 is released with dependent D using A (which auto-updates) and B 0.3, which won't auto-update.

Please ignore the latter as I think it's not necessary to protect downstream from that possibility with pre-release crates. This should only be done with 'alpha' releases of released software to not create issues like the ones encountered recently with clap.

edward-shen · 2021-08-24T16:22:21Z

STABILITY.md

+    │    │ │  git-odb  │       │  git-ref  │ │    │
+    │    │ └───────────┘       └───────────┘ │    │
+    │    │ ┌───────────┐       ┌───────────┐ │    │
+    │    │ │git-config │       │ git-pack  │ │    │


git-config is still pre-1.0, which would be a tier 3 stability.

How can it be made clearer that this is an example for the structure of crates and their maximum stability tier?

Looking at it again I do realize that git-repository plans to provide direct struct field access to something from git-config, so that would make it ST1.

It's probably better to hide these types or to commit to more stability once it goes 1.0.

edward-shen · 2021-08-24T16:25:56Z

STABILITY.md

+
+It is as low as it can be for the crate in questions. While there is no non-pre-release of a tier 1 crate, the MSRV is automatically assumed to be the latest stable version.
+
+Increasing the MSRV is not considered a breaking change and doesn't warrant a major version bump itself.


Is this convention? My intuition of semver would be that bumping MSRV would be considered backwards incompatible, but I suppose this isn't part of the API, so semver doesn't strictly apply here.

Should we make it at least a minor version bump? And/or suggest that we will attempt (but not guarantee) to only change msvp at minor or major versions?

Is this convention? My intuition of semver would be that bumping MSRV would be considered backwards incompatible, but I suppose this isn't part of the API, so semver doesn't strictly apply here.

That was also my first intuition, strictly speaking the MSRV (as well as the edition) affect stability and can break existing users. However, from what I reckon in the MSRV implementation for cargo nightly, cargo will be able to select only crates that have a matching msrv. So it won't select a patch level that would potentially break you.

Should we make it at least a minor version bump?

Whether minor or patch, it's the same effect on downstream crates as without cargo support, they will automatically update.

And/or suggest that we will attempt (but not guarantee) to only change msvp at minor or major versions?

Something like this I had written there before but removed it for the sake of simplicity and the preference for "let's wait for actual demand before complicating our life".

After re-reading this paragraph I realised it was a little 'split' with portions of the old text and the new one. It has now made clear that the MSRV is the latest stable unless there is demand for setting it. Hence this is likely to be revisited at some point.

…sitory` This would also mean that we have to re-create the entire API surface, which seems fair since the high-level API should be fully sufficient to handle all the tasks.

…but suggest pinning of alpha crates instead to avoid accidental breakage. Pre-release crates shouldn't break you unless you end up with multiple incompatible version of the same plumbing crate, which is impossible to prevent just on our side.

…even though it's not quite possible just yet due to leaking abstracitons, whose fix challenges the current sets of crates and their tiers. Some lower level types can greatly benefit from higher tiers.

…which are a subset of primitives that are so basic that it's easy to keep them in ST1, and let `git-repository` use them in its API.

Byron · 2021-08-25T03:41:20Z

@edward-shen Something new just emerged: Foundation Crates. The motivation of this tiered system is to have the least amount of crates commit to a long time between potentially breaking major releases. git-repository acts as a boundary, providing useful and convenient functionality with high stability guarantees.

However it's unnecessarily hard to seal off all the details of the underlying crates which are usually exposed with types. For example, to keep a list of object ids most efficiently, you want to use git_hash::ObjectId. There are some useful types defined in the git_ref crate as well which are worth using even (or particularly) in ST1. The same, I believe, will hold true for git-config usage, which probably can provide access to some Value type. This why I have tentatively added a new crate, git-config-base (name is… probably not the best 😅, it only contains types, so maybe git-config-types is more specific), which could contain such a Value type.

However, it might well be possible that this isn't ever required as the API would be more like get_bool, get_int and so worth, but I think something more generic with conversions akin to get("foo.bar").to_int()? is neater.

What do you think?

…to avoid unnecessary crate splits which, in the case of `git-ref` don't really help that much given there are sub-objects like reflogs which would need complete wrapping. This might one day happen, but until then we can just plan for these to become ST1. Maybe that changes.

Byron · 2021-08-25T04:09:00Z

@edward-shen I probably should hold back in writing comments for a few minutes so that I can avoid back-paddling like now. When trying rip out git-ref-base I noticed that there is also ref logs to consider. And there is probably more and I realized that a whole lot of work would be caused by trying to not commit to stability tier 1 for git-ref or git-config. And I wonder why, just because there are still in pre-release and it will take them some time to stabilize. When that is done, it seems fair and standard business to grant them some stability and maybe keep things simpler.

Of course, as more and more of the git-repository API materializes I might still change my mind for git-ref and summon a git-ref-base, but for now there shouldn't be a strong need.

This means it can use its types freely.

…as just now happened with git-lock and git-tempfile.

Byron · 2021-08-25T07:09:30Z

Thanks for everyones involvement. I am merging this branch because I plan some more breaking changes in ST3 crates to scratch them off the list of things that always bothered me, but am afraid of merge conflicts.

I invite additional discussions and changes in a discussion or PR. Thanks for your understanding.

edward-shen · 2021-08-25T19:45:40Z

However, it might well be possible that this isn't ever required as the API would be more like get_bool, get_int and so worth, but I think something more generic with conversions akin to get("foo.bar").to_int()? is neater.

For what it's worth GitConfig already provides a .value() type that's generic over TryFrom<Cow<'a, [u8]>>, and all Values implement that conversion trait.

Honestly, looking at git-config as a whole, there really shouldn't be a lot of changes with the existing feature set, so maybe one multi-file configs are implemented (on that in a sec) and docs are done, we could possible push for a 1.0.0 to make things easier that just contains everything up to system-wide git configurations.

On getting stuff implemented, I've been in the process of moving across the US (NY to CA) these few months. I'll try to get something done with the prefix issue resolved on the plane. Is there a specific timeframe you're aiming for for a 1.0.0 release of git-repository, or was this just a "lets get this settled?"

Byron · 2021-08-26T00:49:55Z

Honestly, looking at git-config as a whole, there really shouldn't be a lot of changes with the existing feature set, so maybe one multi-file configs are implemented (on that in a sec) and docs are done, we could possible push for a 1.0.0 to make things easier that just contains everything up to system-wide git configurations.

On getting stuff implemented, I've been in the process of moving across the US (NY to CA) these few months. I'll try to get something done with the prefix issue resolved on the plane. Is there a specific timeframe you're aiming for for a 1.0.0 release of git-repository, or was this just a "lets get this settled?"

With this stability initiative I by no means want to push for 1.0 releases, but meant to write down how I can imagine a path towards stabilization. To my mind, with actual usage can come stability, and I think git-config can be used as soon as it supports cascaded configuration file. Because I always forget about it myself, do you also have the include directive on the radar? This allows to further compose the stacks of files, even conditionally so based on contextual information, and might be good to keep in mind when working on the cascading.

I wish you the best of times in California :)!

[stability #164] First sketch of stability MD…

a7353cd

…which lacks a lot of explanation. It uses monodrap to for nice structural diagrams, see https://monodraw.helftone.com for more.

Byron mentioned this pull request Aug 24, 2021

Transform radicle-link integration test setup (as much as possible) to gitoxide #164

Closed

9 tasks

Byron added 4 commits August 24, 2021 14:50

[stability #171] Rough descriptions of ST 3 and 2

340935c

[stability #171] finish tier description…

4fe1259

…and add notes to some support `cargo smart-release` will have to provide. Also don't let it kill build-metadata for no reason, for now.

[stability #171] about transitioning from pre-release to release

bdbdb65

[stability #171] How to handle the MSRV

9be1fce

Let's keep it very simple for now and allow ourselves to keep up to date with stable. That way we get to use the latest clippy which is really the selling point right now.

[stability #171] update README with stability information…

f330daa

…now it's a thing!

edward-shen reviewed Aug 24, 2021

View reviewed changes

Byron added 7 commits August 25, 2021 08:34

[stability #171] Don't provide access to less stable crates in `Respo…

e4c5b58

…sitory` This would also mean that we have to re-create the entire API surface, which seems fair since the high-level API should be fully sufficient to handle all the tasks.

[stability #171] Further loosen MSRV constraints

6b1095a

[stability #171] document git-repository cargo features

8f21e3d

Merge branch 'main' into stability

11bae43

[smart-release #171] Try to avoid unstable git-repository features…

c8f325b

…even though it's not quite possible just yet due to leaking abstracitons, whose fix challenges the current sets of crates and their tiers. Some lower level types can greatly benefit from higher tiers.

[stability #171] Add the concept of Foundation Crates…

8819bde

…which are a subset of primitives that are so basic that it's easy to keep them in ST1, and let `git-repository` use them in its API.

Byron added 5 commits August 25, 2021 12:10

[stability #171] fix schematic

999e813

[stability #171] git-ref is now ST1 and available through git-repository

50154cd

This means it can use its types freely.

[stability #171] does this fix the issue with cargo doc?

0475532

[stability #171] mark git-hash and git-actor as ST1 as well

32caae1

[stability #171] Prime git-tempfile and git-lock for release

01278fe

Byron added 4 commits August 25, 2021 14:51

[stability #171] prepare git-lock and git-tempfile release

3a1cf4d

[smart-release #171] it's about time we get some tests

48a489b

Release git-tempfile v1.0.0

1238535

Release git-lock v1.0.0

f38f72c

Byron added a commit that referenced this pull request Aug 25, 2021

[stability #171] Another question to ask before stabilizing a crate…

c2bc1a6

…as just now happened with git-lock and git-tempfile.

Byron merged commit f38f72c into main Aug 25, 2021

Byron deleted the stability branch August 25, 2021 07:09

Byron added a commit that referenced this pull request Aug 25, 2021

[stability #171] rename immutable::Signature to SignatureRef!

47f0626

Byron added a commit that referenced this pull request Aug 25, 2021

[stability #171] refactor

0870f3c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A draft for a stability guide #171

A draft for a stability guide #171

Byron commented Aug 24, 2021 •

edited

Loading

kim commented Aug 24, 2021

Byron commented Aug 24, 2021 •

edited

Loading

kim commented Aug 24, 2021 via email

Byron commented Aug 24, 2021

Byron commented Aug 24, 2021

edward-shen Aug 24, 2021

Byron Aug 25, 2021

Byron Aug 25, 2021

edward-shen Aug 24, 2021

Byron Aug 25, 2021

edward-shen Aug 24, 2021

Byron Aug 25, 2021

Byron commented Aug 25, 2021

Byron commented Aug 25, 2021

Byron commented Aug 25, 2021

edward-shen commented Aug 25, 2021

Byron commented Aug 26, 2021


		It is as low as it can be for the crate in questions. While there is no non-pre-release of a tier 1 crate, the MSRV is automatically assumed to be the latest stable version.

		Increasing the MSRV is not considered a breaking change and doesn't warrant a major version bump itself.

A draft for a stability guide #171

A draft for a stability guide #171

Conversation

Byron commented Aug 24, 2021 • edited Loading

kim commented Aug 24, 2021

Byron commented Aug 24, 2021 • edited Loading

kim commented Aug 24, 2021 via email

Byron commented Aug 24, 2021

Byron commented Aug 24, 2021

edward-shen Aug 24, 2021

Choose a reason for hiding this comment

Byron Aug 25, 2021

Choose a reason for hiding this comment

Byron Aug 25, 2021

Choose a reason for hiding this comment

edward-shen Aug 24, 2021

Choose a reason for hiding this comment

Byron Aug 25, 2021

Choose a reason for hiding this comment

edward-shen Aug 24, 2021

Choose a reason for hiding this comment

Byron Aug 25, 2021

Choose a reason for hiding this comment

Byron commented Aug 25, 2021

Byron commented Aug 25, 2021

Byron commented Aug 25, 2021

edward-shen commented Aug 25, 2021

Byron commented Aug 26, 2021

Byron commented Aug 24, 2021 •

edited

Loading

Byron commented Aug 24, 2021 •

edited

Loading