Merge rust-bitcoin#2713: Check for changes to the public API

76331ae Add a just cmd to check for API changes (Tobin C. Harding)
b222f40 CI: Add job to check for API changes (Tobin C. Harding)
9e7cd97 Add a script to check the public API (Tobin C. Harding)

Pull request description:

  This PR is rust-bitcoin#1880 re-opened.

  Add a script that checks the public API of `hashes` and `bitcoin`. Document how to use it during development. Call it in CI. Do not add it to githooks because the githooks because its expected to be run per PR not per commit.

  Includes a `just` command to run the script: `just check-api`

  ### Implied workflow change

  This PR imposes workflow changes.

  Explicitly: all PRs that change the public API of `bitcoin`, `base58`, `hashes`, `io`, or `units` must contain changes to the api text files.

  Suggestion: We add the patch updating api text files as a separate patch at the end of each PR so we can haggle over it separately from the actual code changes.

  Fix: rust-bitcoin#1875

ACKs for top commit:
  apoelstra:
    ACK 76331ae normally would complain about the whitespace but I would like to ACK/merge this quickly since most other PR that gets merged will force it to be rebased. also will one-ACK merge as "no NACKs or comments from maintainers in 2 weeks"

Tree-SHA512: 67b20e2ce0c22aa67be931c4da0b591bc351ccb1aa620003c60bfb4b10d5c292edceca929bf6318993f2d16f9f58374aac336adf0f8234c5e2f16e3857b7901b

.github/workflows/rust.yml

@@ -316,3 +316,21 @@ jobs:
         uses: model-checking/kani-github-action@v1.1
         with:
           args: "--only-codegen"
+
+  API:
+    needs: Prepare
+    name: API - nightly toolchain
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - name: "Checkout repo"
+        uses: actions/checkout@v4
+      - name: "Select toolchain"
+        uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: ${{ needs.Prepare.outputs.nightly_version }}
+      - name: "Install cargo-public-api"
+        run: cargo install --locked cargo-public-api
+      - name: "Run API checker script"
+        run: ./contrib/check-for-api-changes.sh

CONTRIBUTING.md

@@ -226,6 +226,11 @@ Use of `unsafe` code is prohibited unless there is a unanimous decision among
 library maintainers on the exclusion from this rule. In such cases there is a
 requirement to test unsafe code with sanitizers including Miri.
 
+### API changes
+
+All PRs that change the public API of `rust-bitcoin` must include a patch to
+the `api/` text files. This should be a separate, final patch to the PR
+that is the diff created by running `./contrib/check-for-api-changes.sh`.
 
 ### Policy
 

api/README.md

@@ -0,0 +1,12 @@
+# API text files
+
+Each file here lists the public API when built with some set of features
+enabled. To create these files run `../contrib/check-for-api-changes.sh`:
+
+Requires `cargo-public-api`, install with:
+
+```
+cargo +stable install cargo-public-api --locked
+```
+
+ref: https://github.com/enselic/cargo-public-api

api/base58/default-features.txt

@@ -0,0 +1,100 @@
+#[non_exhaustive] pub enum base58ck::Error
+#[non_exhaustive] pub enum base58ck::error::Error
+impl base58ck::error::IncorrectChecksumError
+impl base58ck::error::InvalidCharacterError
+impl base58ck::error::TooShortError
+impl core::clone::Clone for base58ck::error::Error
+impl core::clone::Clone for base58ck::error::IncorrectChecksumError
+impl core::clone::Clone for base58ck::error::InvalidCharacterError
+impl core::clone::Clone for base58ck::error::TooShortError
+impl core::cmp::Eq for base58ck::error::Error
+impl core::cmp::Eq for base58ck::error::IncorrectChecksumError
+impl core::cmp::Eq for base58ck::error::InvalidCharacterError
+impl core::cmp::Eq for base58ck::error::TooShortError
+impl core::cmp::PartialEq for base58ck::error::Error
+impl core::cmp::PartialEq for base58ck::error::IncorrectChecksumError
+impl core::cmp::PartialEq for base58ck::error::InvalidCharacterError
+impl core::cmp::PartialEq for base58ck::error::TooShortError
+impl core::convert::From<base58ck::error::IncorrectChecksumError> for base58ck::error::Error
+impl core::convert::From<base58ck::error::InvalidCharacterError> for base58ck::error::Error
+impl core::convert::From<base58ck::error::TooShortError> for base58ck::error::Error
+impl core::convert::From<core::convert::Infallible> for base58ck::error::Error
+impl core::error::Error for base58ck::error::Error
+impl core::error::Error for base58ck::error::IncorrectChecksumError
+impl core::error::Error for base58ck::error::InvalidCharacterError
+impl core::error::Error for base58ck::error::TooShortError
+impl core::fmt::Debug for base58ck::error::Error
+impl core::fmt::Debug for base58ck::error::IncorrectChecksumError
+impl core::fmt::Debug for base58ck::error::InvalidCharacterError
+impl core::fmt::Debug for base58ck::error::TooShortError
+impl core::fmt::Display for base58ck::error::Error
+impl core::fmt::Display for base58ck::error::IncorrectChecksumError
+impl core::fmt::Display for base58ck::error::InvalidCharacterError
+impl core::fmt::Display for base58ck::error::TooShortError
+impl core::marker::Freeze for base58ck::error::Error
+impl core::marker::Freeze for base58ck::error::IncorrectChecksumError
+impl core::marker::Freeze for base58ck::error::InvalidCharacterError
+impl core::marker::Freeze for base58ck::error::TooShortError
+impl core::marker::Send for base58ck::error::Error
+impl core::marker::Send for base58ck::error::IncorrectChecksumError
+impl core::marker::Send for base58ck::error::InvalidCharacterError
+impl core::marker::Send for base58ck::error::TooShortError
+impl core::marker::StructuralPartialEq for base58ck::error::Error
+impl core::marker::StructuralPartialEq for base58ck::error::IncorrectChecksumError
+impl core::marker::StructuralPartialEq for base58ck::error::InvalidCharacterError
+impl core::marker::StructuralPartialEq for base58ck::error::TooShortError
+impl core::marker::Sync for base58ck::error::Error
+impl core::marker::Sync for base58ck::error::IncorrectChecksumError
+impl core::marker::Sync for base58ck::error::InvalidCharacterError
+impl core::marker::Sync for base58ck::error::TooShortError
+impl core::marker::Unpin for base58ck::error::Error
+impl core::marker::Unpin for base58ck::error::IncorrectChecksumError
+impl core::marker::Unpin for base58ck::error::InvalidCharacterError
+impl core::marker::Unpin for base58ck::error::TooShortError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::Error
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::IncorrectChecksumError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::InvalidCharacterError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::TooShortError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::Error
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::IncorrectChecksumError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::InvalidCharacterError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::TooShortError
+pub base58ck::Error::Decode(base58ck::error::InvalidCharacterError)
+pub base58ck::Error::IncorrectChecksum(base58ck::error::IncorrectChecksumError)
+pub base58ck::Error::TooShort(base58ck::error::TooShortError)
+pub base58ck::error::Error::Decode(base58ck::error::InvalidCharacterError)
+pub base58ck::error::Error::IncorrectChecksum(base58ck::error::IncorrectChecksumError)
+pub base58ck::error::Error::TooShort(base58ck::error::TooShortError)
+pub fn base58ck::decode(data: &str) -> core::result::Result<alloc::vec::Vec<u8>, base58ck::error::InvalidCharacterError>
+pub fn base58ck::decode_check(data: &str) -> core::result::Result<alloc::vec::Vec<u8>, base58ck::error::Error>
+pub fn base58ck::encode(data: &[u8]) -> alloc::string::String
+pub fn base58ck::encode_check(data: &[u8]) -> alloc::string::String
+pub fn base58ck::encode_check_to_fmt(fmt: &mut core::fmt::Formatter<'_>, data: &[u8]) -> core::fmt::Result
+pub fn base58ck::error::Error::clone(&self) -> base58ck::error::Error
+pub fn base58ck::error::Error::eq(&self, other: &base58ck::error::Error) -> bool
+pub fn base58ck::error::Error::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::Error::from(e: base58ck::error::IncorrectChecksumError) -> Self
+pub fn base58ck::error::Error::from(e: base58ck::error::InvalidCharacterError) -> Self
+pub fn base58ck::error::Error::from(e: base58ck::error::TooShortError) -> Self
+pub fn base58ck::error::Error::from(never: core::convert::Infallible) -> Self
+pub fn base58ck::error::Error::source(&self) -> core::option::Option<&(dyn core::error::Error + 'static)>
+pub fn base58ck::error::IncorrectChecksumError::clone(&self) -> base58ck::error::IncorrectChecksumError
+pub fn base58ck::error::IncorrectChecksumError::eq(&self, other: &base58ck::error::IncorrectChecksumError) -> bool
+pub fn base58ck::error::IncorrectChecksumError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::IncorrectChecksumError::incorrect_checksum(&self) -> (u32, u32)
+pub fn base58ck::error::InvalidCharacterError::clone(&self) -> base58ck::error::InvalidCharacterError
+pub fn base58ck::error::InvalidCharacterError::eq(&self, other: &base58ck::error::InvalidCharacterError) -> bool
+pub fn base58ck::error::InvalidCharacterError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::InvalidCharacterError::invalid_base58_character(&self) -> u8
+pub fn base58ck::error::TooShortError::clone(&self) -> base58ck::error::TooShortError
+pub fn base58ck::error::TooShortError::eq(&self, other: &base58ck::error::TooShortError) -> bool
+pub fn base58ck::error::TooShortError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::TooShortError::invalid_base58_length(&self) -> usize
+pub mod base58ck
+pub mod base58ck::error
+pub struct base58ck::InvalidCharacterError
+pub struct base58ck::error::IncorrectChecksumError
+pub struct base58ck::error::InvalidCharacterError
+pub struct base58ck::error::TooShortError
+pub use base58ck::String
+pub use base58ck::Vec

api/base58/no-features.txt

@@ -0,0 +1,95 @@
+#[non_exhaustive] pub enum base58ck::Error
+#[non_exhaustive] pub enum base58ck::error::Error
+impl base58ck::error::IncorrectChecksumError
+impl base58ck::error::InvalidCharacterError
+impl base58ck::error::TooShortError
+impl core::clone::Clone for base58ck::error::Error
+impl core::clone::Clone for base58ck::error::IncorrectChecksumError
+impl core::clone::Clone for base58ck::error::InvalidCharacterError
+impl core::clone::Clone for base58ck::error::TooShortError
+impl core::cmp::Eq for base58ck::error::Error
+impl core::cmp::Eq for base58ck::error::IncorrectChecksumError
+impl core::cmp::Eq for base58ck::error::InvalidCharacterError
+impl core::cmp::Eq for base58ck::error::TooShortError
+impl core::cmp::PartialEq for base58ck::error::Error
+impl core::cmp::PartialEq for base58ck::error::IncorrectChecksumError
+impl core::cmp::PartialEq for base58ck::error::InvalidCharacterError
+impl core::cmp::PartialEq for base58ck::error::TooShortError
+impl core::convert::From<base58ck::error::IncorrectChecksumError> for base58ck::error::Error
+impl core::convert::From<base58ck::error::InvalidCharacterError> for base58ck::error::Error
+impl core::convert::From<base58ck::error::TooShortError> for base58ck::error::Error
+impl core::convert::From<core::convert::Infallible> for base58ck::error::Error
+impl core::fmt::Debug for base58ck::error::Error
+impl core::fmt::Debug for base58ck::error::IncorrectChecksumError
+impl core::fmt::Debug for base58ck::error::InvalidCharacterError
+impl core::fmt::Debug for base58ck::error::TooShortError
+impl core::fmt::Display for base58ck::error::Error
+impl core::fmt::Display for base58ck::error::IncorrectChecksumError
+impl core::fmt::Display for base58ck::error::InvalidCharacterError
+impl core::fmt::Display for base58ck::error::TooShortError
+impl core::marker::Freeze for base58ck::error::Error
+impl core::marker::Freeze for base58ck::error::IncorrectChecksumError
+impl core::marker::Freeze for base58ck::error::InvalidCharacterError
+impl core::marker::Freeze for base58ck::error::TooShortError
+impl core::marker::Send for base58ck::error::Error
+impl core::marker::Send for base58ck::error::IncorrectChecksumError
+impl core::marker::Send for base58ck::error::InvalidCharacterError
+impl core::marker::Send for base58ck::error::TooShortError
+impl core::marker::StructuralPartialEq for base58ck::error::Error
+impl core::marker::StructuralPartialEq for base58ck::error::IncorrectChecksumError
+impl core::marker::StructuralPartialEq for base58ck::error::InvalidCharacterError
+impl core::marker::StructuralPartialEq for base58ck::error::TooShortError
+impl core::marker::Sync for base58ck::error::Error
+impl core::marker::Sync for base58ck::error::IncorrectChecksumError
+impl core::marker::Sync for base58ck::error::InvalidCharacterError
+impl core::marker::Sync for base58ck::error::TooShortError
+impl core::marker::Unpin for base58ck::error::Error
+impl core::marker::Unpin for base58ck::error::IncorrectChecksumError
+impl core::marker::Unpin for base58ck::error::InvalidCharacterError
+impl core::marker::Unpin for base58ck::error::TooShortError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::Error
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::IncorrectChecksumError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::InvalidCharacterError
+impl core::panic::unwind_safe::RefUnwindSafe for base58ck::error::TooShortError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::Error
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::IncorrectChecksumError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::InvalidCharacterError
+impl core::panic::unwind_safe::UnwindSafe for base58ck::error::TooShortError
+pub base58ck::Error::Decode(base58ck::error::InvalidCharacterError)
+pub base58ck::Error::IncorrectChecksum(base58ck::error::IncorrectChecksumError)
+pub base58ck::Error::TooShort(base58ck::error::TooShortError)
+pub base58ck::error::Error::Decode(base58ck::error::InvalidCharacterError)
+pub base58ck::error::Error::IncorrectChecksum(base58ck::error::IncorrectChecksumError)
+pub base58ck::error::Error::TooShort(base58ck::error::TooShortError)
+pub fn base58ck::decode(data: &str) -> core::result::Result<alloc::vec::Vec<u8>, base58ck::error::InvalidCharacterError>
+pub fn base58ck::decode_check(data: &str) -> core::result::Result<alloc::vec::Vec<u8>, base58ck::error::Error>
+pub fn base58ck::encode(data: &[u8]) -> alloc::string::String
+pub fn base58ck::encode_check(data: &[u8]) -> alloc::string::String
+pub fn base58ck::encode_check_to_fmt(fmt: &mut core::fmt::Formatter<'_>, data: &[u8]) -> core::fmt::Result
+pub fn base58ck::error::Error::clone(&self) -> base58ck::error::Error
+pub fn base58ck::error::Error::eq(&self, other: &base58ck::error::Error) -> bool
+pub fn base58ck::error::Error::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::Error::from(e: base58ck::error::IncorrectChecksumError) -> Self
+pub fn base58ck::error::Error::from(e: base58ck::error::InvalidCharacterError) -> Self
+pub fn base58ck::error::Error::from(e: base58ck::error::TooShortError) -> Self
+pub fn base58ck::error::Error::from(never: core::convert::Infallible) -> Self
+pub fn base58ck::error::IncorrectChecksumError::clone(&self) -> base58ck::error::IncorrectChecksumError
+pub fn base58ck::error::IncorrectChecksumError::eq(&self, other: &base58ck::error::IncorrectChecksumError) -> bool
+pub fn base58ck::error::IncorrectChecksumError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::IncorrectChecksumError::incorrect_checksum(&self) -> (u32, u32)
+pub fn base58ck::error::InvalidCharacterError::clone(&self) -> base58ck::error::InvalidCharacterError
+pub fn base58ck::error::InvalidCharacterError::eq(&self, other: &base58ck::error::InvalidCharacterError) -> bool
+pub fn base58ck::error::InvalidCharacterError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::InvalidCharacterError::invalid_base58_character(&self) -> u8
+pub fn base58ck::error::TooShortError::clone(&self) -> base58ck::error::TooShortError
+pub fn base58ck::error::TooShortError::eq(&self, other: &base58ck::error::TooShortError) -> bool
+pub fn base58ck::error::TooShortError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn base58ck::error::TooShortError::invalid_base58_length(&self) -> usize
+pub mod base58ck
+pub mod base58ck::error
+pub struct base58ck::InvalidCharacterError
+pub struct base58ck::error::IncorrectChecksumError
+pub struct base58ck::error::InvalidCharacterError
+pub struct base58ck::error::TooShortError
+pub use base58ck::String
+pub use base58ck::Vec