Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SemVer: Update documentation about removing optional dependencies #12687

Merged
merged 1 commit into from
Sep 18, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion src/doc/src/reference/semver.md
Original file line number Diff line number Diff line change
Expand Up @@ -2135,9 +2135,16 @@ std = []

#### Possibly-breaking: removing an optional dependency {#cargo-remove-opt-dep}

Removing an optional dependency can break a project using your library because
Removing an [optional dependency][opt-dep] can break a project using your library because
another project may be enabling that dependency via [Cargo features].

When there is an optional dependency, cargo implicitly defines a feature of
the same name to provide a mechanism to enable the dependency and to check
when it is enabled. This problem can be avoided by using the `dep:` syntax in
the `[features]` table, which disables this implicit feature. Using `dep:`
makes it possible to hide the existence of optional dependencies under more
semantically-relevant names which can be more safely modified.

```toml
# Breaking change example

Expand All @@ -2152,7 +2159,33 @@ curl = { version = "0.4.31", optional = true }
# ..curl removed
```

```toml
# MINOR CHANGE
#
# This example shows how to avoid breaking changes with optional dependencies.

###########################################################
# Before
[dependencies]
curl = { version = "0.4.31", optional = true }

[features]
networking = ["dep:curl"]
Comment on lines +2162 to +2173
Copy link
Contributor

@epage epage Sep 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think its fine for us to suggest this be treated as minor. The main risk is rust-lang/rust#109005 as people might be seeing the internal names and using them. I actually saw someone mislead by this when demoing the compiler error (the entire serde example was driven by what the compiler said) .


###########################################################
# After
[dependencies]
# Here, one optional dependency was replaced with another.
hyper = { version = "0.14.27", optional = true }

[features]
networking = ["dep:hyper"]
```

Mitigation strategies:
* Use the `dep:` syntax in the `[features]` table to avoid exposing optional
dependencies in the first place. See [optional dependencies][opt-dep] for
more information.
* Clearly document your features. If the optional dependency is not included
in the documented list of features, then you may decide to consider it safe
to change undocumented entries.
Expand All @@ -2166,6 +2199,8 @@ Mitigation strategies:
optional dependencies necessary to implement "networking". Then document the
"networking" feature.

[opt-dep]: features.md#optional-dependencies

#### Minor: changing dependency features {#cargo-change-dep-feature}

It is usually safe to change the features on a dependency, as long as the
Expand Down