Requires unstable feature (#3772)

* Add `requires-unstable` feature

* Docs

* CHANGELOG.md

* Advise for library authors

esp-hal-embassy/Cargo.toml

@@ -21,7 +21,7 @@ test  = false
 [dependencies]
 cfg-if                    = "1.0.0"
 critical-section          = "1.2.0"
-esp-hal                   = { version = "1.0.0-beta.1", path = "../esp-hal" }
+esp-hal                   = { version = "1.0.0-beta.1", path = "../esp-hal", features = ["requires-unstable"] }
 portable-atomic           = "1.11.0"
 static_cell               = "2.1.0"
 

esp-hal/CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ESP32-C6: GPIO6 now implements `AnalogPin` (#3668)
 - SPI master: Expose octal SPI-specific `with_sio` functions (#3702)
 - Added GPIO11-GPIO17 to ESP32-C2. (#3726)
+- Added the feature `requires-unstable` (#3772)
 
 ### Changed
 

esp-hal/Cargo.toml

@@ -209,6 +209,7 @@ psram = []
 #! Unstable APIs are not covered by semver guarantees.
 
 ## Enables APIs that are not stable and thus come with no stability guarantees.
+## Never enable this feature in a library crate using esp-hal.
 unstable = [
     "dep:digest",
     "dep:embassy-embedded-hal",
@@ -221,6 +222,12 @@ unstable = [
     "dep:ufmt-write",
 ]
 
+## Libraries that depend on `esp-hal` should enable this feature to indicate their use of unstable APIs.
+## However, they must **not** enable the `unstable` feature themselves.
+##
+## For development you can enable the `unstable` and the chip feature by adding esp-hal as a dev-dependency.
+requires-unstable = []
+
 [lints.clippy]
 mixed_attributes_style = "allow"
 

esp-hal/build.rs

@@ -28,6 +28,13 @@ fn main() -> Result<(), Box<dyn Error>> {
         }
     }
 
+    // If some library required unstable make sure unstable is actually enabled.
+    if cfg!(feature = "requires-unstable") && !cfg!(feature = "unstable") {
+        panic!(
+            "\n\nThe `unstable` feature is required by a dependent crate but is not enabled.\n\n"
+        );
+    }
+
     // Log and defmt are mutually exclusive features. The main technical reason is
     // that allowing both would make the exact panicking behaviour a fragile
     // implementation detail.

esp-ieee802154/Cargo.toml

@@ -21,7 +21,7 @@ test  = false
 [dependencies]
 cfg-if            = "1.0.0"
 critical-section  = "1.2.0"
-esp-hal           = { version = "1.0.0-beta.1", path = "../esp-hal" }
+esp-hal           = { version = "1.0.0-beta.1", path = "../esp-hal", features = ["requires-unstable"] }
 
 # ⚠️ Unstable dependencies that are part of the public API
 heapless          = "0.8.0"

esp-wifi/Cargo.toml

@@ -15,7 +15,7 @@ bench = false
 test  = false
 
 [dependencies]
-esp-hal = { version = "1.0.0-beta.1", path = "../esp-hal", default-features = false }
+esp-hal = { version = "1.0.0-beta.1", path = "../esp-hal", default-features = false, features = ["requires-unstable"] }
 critical-section = "1.2.0"
 cfg-if = "1.0.0"
 portable-atomic = { version = "1.11.0", default-features = false }