From 096652f2ea34fa075d7cd0cd93ba10c9af628520 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 25 Aug 2023 11:20:45 -0500 Subject: [PATCH 1/5] Announce change in Cargo.lock policy --- posts/2023-09-01-committing-lockfiles.md | 64 ++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 posts/2023-09-01-committing-lockfiles.md diff --git a/posts/2023-09-01-committing-lockfiles.md b/posts/2023-09-01-committing-lockfiles.md new file mode 100644 index 000000000..c516fcd22 --- /dev/null +++ b/posts/2023-09-01-committing-lockfiles.md @@ -0,0 +1,64 @@ +--- +layout: post +title: "Change in Guidance on Committing Lockfiles" +author: Ed Page +team: The Cargo Team +--- + +For years, the Cargo team has encouraged Rust developers to +[commit their `Cargo.lock` file for packages with binaries but not libraries](https://doc.rust-lang.org/1.71.1/cargo/faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). +We now recommend people +[do what is best for their project](https://doc.rust-lang.org/nightly/cargo/faq.html#why-have-cargolock-in-version-control). +To help people make a decision, we do include some considerations and suggest +committing `Cargo.lock` as a starting point in your decision making. +To align with that starting point, `cargo new` will no longer ignore +`Cargo.lock` for libraries as of nightly-2023-08-24. +Regardless of what decision you make, we encourage regular +[testing against your latest dependencies](https://doc.rust-lang.org/nightly/cargo/guide/continuous-integration.html#verifying-latest-dependencies). + +## Background + +The old guidelines ensured libraries tested their latest dependencies which +helped us keep quality high within Rust's package ecosystem by ensuring issues, +especially backwards compatibility issues, +were quickly found and addressed. +While this extra testing was not exhaustive, +We believe it helped foster a culture of quality in this nascent ecosystem. + +This hasn't been without its downsides though. +This has removed an important piece of history from code bases, +making bisecting to find the root cause of a bug harder for maintainers. +For contributors, +especially newer ones, +this is another potential source of confusion and frustration from an unreliable CI whenever a +dependency is yanked or a new release contains a bug. + +## Why the change + +A lot as changed for Rust since the guideline was written. +Rust has shifted from being a language for early adopters to being more mainstream, +and we need to be mindful of the on-boarding experience of these new-to-Rust developers. +Also with this wider adoption, it isn't always practical to assume everyone is using +the latest Rust release and the community has been working through how to +manage support for minimum-supported Rust versions (MSRV). +Part of this is maintaining an instance of your dependency tree that can build +with your MSRV. +A lockfile is an appropriate way to pin versions for your project so you +can validate your MSRV but we found people were instead putting upperbounds on their +version requirements due to the strength of our prior guideline despite +[likely being a worse solution](https://doc.rust-lang.org/nightly/cargo/reference/specifying-dependencies.html#multiple-requirements). + +The wider software development ecosystem has also changed a lot in the +intervening time. +CI has become easier to setup and maintain. +We also have products like +[Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot) +and +[Renovate](https://docs.renovatebot.com/). +This has opened up options besides having version control ignore `Cargo.lock` to test newer dependencies. +Developers could have a scheduled job that first runs `cargo update`. +They could also have bots regularly update their `Cargo.lock` in PRs, ensuring +they pass CI before being merged. + +Since there isn't a universal answer to these situations, +we felt it was best to give developers the information they need in making a decision. From 91de75f29ce1149d27889f166f082dbdf49706fb Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 25 Aug 2023 11:25:36 -0500 Subject: [PATCH 2/5] Tweaks to language --- posts/2023-09-01-committing-lockfiles.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/posts/2023-09-01-committing-lockfiles.md b/posts/2023-09-01-committing-lockfiles.md index c516fcd22..d9bf4d44b 100644 --- a/posts/2023-09-01-committing-lockfiles.md +++ b/posts/2023-09-01-committing-lockfiles.md @@ -10,11 +10,11 @@ For years, the Cargo team has encouraged Rust developers to We now recommend people [do what is best for their project](https://doc.rust-lang.org/nightly/cargo/faq.html#why-have-cargolock-in-version-control). To help people make a decision, we do include some considerations and suggest -committing `Cargo.lock` as a starting point in your decision making. +committing `Cargo.lock` as a starting point in their decision making. To align with that starting point, `cargo new` will no longer ignore `Cargo.lock` for libraries as of nightly-2023-08-24. -Regardless of what decision you make, we encourage regular -[testing against your latest dependencies](https://doc.rust-lang.org/nightly/cargo/guide/continuous-integration.html#verifying-latest-dependencies). +Regardless of what decision projects make, we encourage regular +[testing against their latest dependencies](https://doc.rust-lang.org/nightly/cargo/guide/continuous-integration.html#verifying-latest-dependencies). ## Background From 098b07c09e28150b94e3e7f07f8345547c2d54c8 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 25 Aug 2023 11:42:08 -0500 Subject: [PATCH 3/5] Tweaked closing paragraph --- posts/2023-09-01-committing-lockfiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/2023-09-01-committing-lockfiles.md b/posts/2023-09-01-committing-lockfiles.md index d9bf4d44b..d709ec250 100644 --- a/posts/2023-09-01-committing-lockfiles.md +++ b/posts/2023-09-01-committing-lockfiles.md @@ -61,4 +61,4 @@ They could also have bots regularly update their `Cargo.lock` in PRs, ensuring they pass CI before being merged. Since there isn't a universal answer to these situations, -we felt it was best to give developers the information they need in making a decision. +we felt it was best to leave the choice to developers and give them information they need in making a decision. From 6f5028967cdeaa94a6681ffa9b8909324a46b1c4 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 25 Aug 2023 12:29:03 -0500 Subject: [PATCH 4/5] Add feedback links --- posts/2023-09-01-committing-lockfiles.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/posts/2023-09-01-committing-lockfiles.md b/posts/2023-09-01-committing-lockfiles.md index d709ec250..d157d74fb 100644 --- a/posts/2023-09-01-committing-lockfiles.md +++ b/posts/2023-09-01-committing-lockfiles.md @@ -62,3 +62,7 @@ they pass CI before being merged. Since there isn't a universal answer to these situations, we felt it was best to leave the choice to developers and give them information they need in making a decision. +For feedback on this policy change, +see [rust-lang/cargo#8728](https://github.com/rust-lang/cargo/issues/8728). +You can also reach out the the Cargo team more generally on +[Zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo). From 9181364eefcf03ec5ded60a63d1bc8ccb9505a92 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 28 Aug 2023 11:19:06 -0500 Subject: [PATCH 5/5] Expect the post to be merged tomorrow --- ...committing-lockfiles.md => 2023-08-29-committing-lockfiles.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename posts/{2023-09-01-committing-lockfiles.md => 2023-08-29-committing-lockfiles.md} (100%) diff --git a/posts/2023-09-01-committing-lockfiles.md b/posts/2023-08-29-committing-lockfiles.md similarity index 100% rename from posts/2023-09-01-committing-lockfiles.md rename to posts/2023-08-29-committing-lockfiles.md