xtask: Add SemVer checks for esp-rom-sys

[JurajSadel]

This might be a bit of a hacky solution, but I tried to convince cargo-semver-checks that esp-rom-sys is not intended to ever reach 1.0, and I failed.

To test this, I changned a pub fn name in esp-rom-sys/src/rom/crc.rs:

-pub fn crc8_be(crc: u8, buf: &[u8]) -> u8 {
+pub fn crc8_be_change(crc: u8, buf: &[u8]) -> u8 {

Ran cargo xrelease plan esp-rom-sys --allow-non-main:

[2025-12-01T14:51:54Z INFO  xtask::commands::release::semver_check::checker] Downloading API baselines for esp-rom-sys
[2025-12-01T14:51:54Z INFO  xtask::commands::release::semver_check::checker] Attempting to download from GitHub Actions artifact: api-baselines-esp-rom-sys
[2025-12-01T14:51:54Z INFO  xtask::commands::release::semver_check::checker] Attempting to download artifact: api-baselines-esp-rom-sys from esp-rs/esp-hal
[2025-12-01T14:51:56Z INFO  xtask::commands::release::semver_check::checker] Successfully downloaded baselines from artifact api-baselines-esp-rom-sys
[2025-12-01T14:51:56Z INFO  xtask::commands::release::semver_check::checker] Found 7 baseline files for esp-rom-sys
    Checking <unknown> v0.1.3 -> v0.1.3 (no change; assume minor)
     Checked [   0.024s] 140 checks: 139 pass, 1 fail, 0 warn, 38 skip

--- failure function_missing: pub fn removed or renamed ---

Description:
A publicly-visible function cannot be imported by its prior path. A `pub use` may have been removed, or the function itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.43.0/src/lints/function_missing.ron

Failed in:
  function esp_rom_sys::rom::crc::crc8_be, previously in file src/rom/crc.rs:122

     Summary semver requires new major version: 1 major and 0 minor checks failed

Summary semver requires new major version: 1 major and 0 minor checks failed

Is the reason for the "hacky" solution.

The final .jsonc:

{
  "base": "esp-rom-sys-semver",
  "packages": [
    {
      "package": "esp-metadata-generated",
      "semver_checked": false,
      "current_version": "0.3.0",
      "new_version": "0.4.0",
      "tag_name": "esp-metadata-generated-v0.4.0",
      "bump": "Minor"
    },
    {
      "package": "esp-rom-sys",
      "semver_checked": true,
      "current_version": "0.1.3",
      "new_version": "0.2.0",
      "tag_name": "esp-rom-sys-v0.2.0",
      "bump": "Minor"
    }
  ]
}

closes #4489

[MabezDev]

FYI, there is cargo xcheck semver-check check which will download the baselines and test against the current local code. Would be good to test that this works with more than just esp-hal.

[bugadani]

I don't mind doing this, but it's worth mentioning that what the release tool considers Major/Minor/Patch don't actually match semver's idea of "0.x -> 0.x+1 is a major bump".

[JurajSadel]

FYI, there is cargo xcheck semver-check check which will download the baselines and test against the current local code. Would be good to test that this works with more than just esp-hal.

I tested it (with the same change in esp-rom-sys as in the description) and the result is the same for esp-rom-sys. How esp-hal:

Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.01s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32-none-elf/doc/esp_hal.json
    Checking <unknown> v1.0.0-rc.0 -> v1.0.0 (major change)
     Checked [   0.000s] 0 checks: 0 pass, 178 skip
     Summary no semver update required
    Finished [   0.204s] <unknown>

So, we need to re-generate the baselines for esp-hal and I changed impl<'d> Uart<'d, Blocking>

-    pub fn new(uart: impl Instance + 'd, config: Config) -> Result<Self, ConfigError> {
+    pub fn new1(uart: impl Instance + 'd, config: Config) -> Result<Self, ConfigError> {

and ran cargo xcheck semver-check check:

Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.01s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32-none-elf/doc/esp_hal.json
    Checking <unknown> v1.0.0 -> v1.0.0 (no change; assume patch)
     Checked [   0.081s] 165 checks: 164 pass, 1 fail, 0 warn, 13 skip

--- failure inherent_method_missing: pub method removed or renamed ---

Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32s3-none-elf/doc/esp_rom_sys.json
    Checking <unknown> v0.1.3 -> v0.1.3 (no change; assume minor)
     Checked [   0.023s] 140 checks: 139 pass, 1 fail, 0 warn, 38 skip

--- failure function_missing: pub fn removed or renamed ---

So, it should be working correctly (with re-generated baseline for esp-hal).

[JurajSadel]

Is anything else needed here, please?

[MabezDev]

FYI, there is cargo xcheck semver-check check which will download the baselines and test against the current local code. Would be good to test that this works with more than just esp-hal.

I tested it (with the same change in esp-rom-sys as in the description) and the result is the same for esp-rom-sys. How esp-hal:

Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.01s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32-none-elf/doc/esp_hal.json
    Checking <unknown> v1.0.0-rc.0 -> v1.0.0 (major change)
     Checked [   0.000s] 0 checks: 0 pass, 178 skip
     Summary no semver update required
    Finished [   0.204s] <unknown>

So, we need to re-generate the baselines for esp-hal and I changed impl<'d> Uart<'d, Blocking>

-    pub fn new(uart: impl Instance + 'd, config: Config) -> Result<Self, ConfigError> {
+    pub fn new1(uart: impl Instance + 'd, config: Config) -> Result<Self, ConfigError> {

and ran cargo xcheck semver-check check:

Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.01s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32-none-elf/doc/esp_hal.json
    Checking <unknown> v1.0.0 -> v1.0.0 (no change; assume patch)
     Checked [   0.081s] 165 checks: 164 pass, 1 fail, 0 warn, 13 skip

--- failure inherent_method_missing: pub method removed or renamed ---

Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s
   Generated /Users/jurajsadel/esp-rs/esp-hal/target/xtensa-esp32s3-none-elf/doc/esp_rom_sys.json
    Checking <unknown> v0.1.3 -> v0.1.3 (no change; assume minor)
     Checked [   0.023s] 140 checks: 139 pass, 1 fail, 0 warn, 38 skip

--- failure function_missing: pub fn removed or renamed ---

So, it should be working correctly (with re-generated baseline for esp-hal).

Can you add a test for this logic within the xtask? This kind of information is forgotten quickly, best to have the test there to enforce that how it behaves now is correct.

[MabezDev]

I'd like to see a test for the amount bump on packages that are stable and those that are not. Please also address @bjoernQ's comment here.

[MabezDev]

This test actually gives some insight to my original request.

What does Minor mean here?

If the package is x.y.z, where x < 1 does minor bump refer to y or z?

[JurajSadel]

It refers to y.

[MabezDev]

Then I think it's wrong, because when it comes to executing the plan we'll bail: https://github.com/esp-rs/esp-hal/pull/4584/files#diff-9997b515b11572bd537642c3209a3536024714fe89ca34421bb69cdeb6db3d24R68-R73

forever unstable should only receive patch releases (I guess we need to document this somewhere)

[JurajSadel]

I might be missing something here but how do we want to deal with breaking changes in esp-rom-sys if only patch release is valid?

[MabezDev]

That's actually the whole point, we never want breaking changes in esp-rom-sys. It needs to be stable API forever (without being a stable version). That's why were adding this check, and the checks in your other PRs.

The reason for this (is the same reason why the libc crate is stuck at 0.2.x) is that we use links in this crate, meaning we can only ever have one version in the crate graph, and this crate is used all over the place an an impl detail. If we have two semver incompatible versions released/used it will break downstream users.

[bjoernQ]

we never want breaking changes in esp-rom-sys

That was the initial assumption and it will hold true until we need to update the radio blobs.

What makes all of this a bit more complex is, (in my point of view) we have three different "tiers" of items this crate provides:

• the Rust helpers / wrappers (this is the easiest part - we just don't want to see anything breaking here, ever)
• some symbols we rely on (i.e. common ROM functions we use in other crates ... we just don't want to see anything breaking here, ever - but that's only a hand full of symbols)
• a lot of other symbols we don't even can know what their meaning is (the tricky part ... when the blobs in esp-idf are updated it's quite common that ROM functions get commented out and are replaced by code found in the blobs )
• (in theory another category: ROM functions replaced by libesp_rom.a ... but that is not a problem since that happens inside esp-rom-sys ... which makes we wonder if we should/need to take that (symbols from libesp_rom.a) into account here?)

So what to do here and now?

I have ideas how to overcome the above problems but we need to carefully validate these (and hope one of them will work). In any case it's far beyond the scope of this PR.

We can just assume our original assumption about this to never see any breaking changes will hold true and just don't allow anything beyond a patch-version bump here. This PR should help us to uphold this requirement.

And we need to open a new issue to find a solution for the outlined (forseeable) problems. (we will need to solve that before the next blob update)

The outcome of that new issue might even be that we will need breaking changes but hopefully not.

[JurajSadel]

I opened #4675