Check for changes to the public API

We would like to get to a stage where we can commit to the public API.
To help us achieve this add a script that generates the public API and
checks it against three committed files, one for each feature set: no
features, alloc, std.

The idea is that with this applied any PR that changes the public API
should include a final patch that is just the changes to the api/*.txt
files, that way reviewers can discuss the changes without even needing
to look at the code, quickly giving concept ACK/NACKs. We also run the
script in CI to make sure we have not accidentally changed the public
API so that we can be confident that don't break semver during releases.
The script can also be used to diff between two release versions to get
a complete list of API changes, useful for writing release notes and for
users upgrading.

There is a development burden involved if we apply this patch.

changelog:
    section: dev
    inherit: title
    description: Generate the full public API as a set of text files and
    commit them to the repository, for each subsequent PR do the same
    and check that the final state of the pubic API is not different.
    Implies that changing the public API requires a patch to the
    committed API text files.

.github/workflows/rust.yml

@@ -140,3 +140,18 @@ jobs:
         run: cargo install cross --locked
       - name: run cross test
         run: cross test --target s390x-unknown-linux-gnu
+
+  API:
+    name: Check for changes to the public API
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Checkout Crate
+        uses: actions/checkout@v3
+      - name: Checkout Toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - name: Install cargo-public-api
+        run: cargo install --locked cargo-public-api
+      - name: Running API checker script
+        run: ./contrib/check-for-api-changes.sh

README.md

@@ -33,3 +33,10 @@ Alternatively add symlinks in your `.git/hooks` directory to any of the githooks
 
 We use a custom Rust compiler configuration conditional to guard the benchmark code. To run the
 benchmarks use: `RUSTFLAGS='--cfg=bench' cargo +nightly bench`.
+
+
+## API changes
+
+All PRs that change the public API of `rust-bech32` must include a patch to the
+`api/` text files. For PRs that include API changes, add a separate patch to the PR
+that is the diff created by running `contrib/check-for-api-changes.sh`.