Merge rust-bitcoin/rust-secp256k1#656: Check for changes to the public API

e9e17a00393bad3db5d8d8654eb1f4bf1f20cbbb Check for changes to the public API (Tobin C. Harding)

Pull request description:

  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.

ACKs for top commit:
  apoelstra:
    ACK e9e17a00393bad3db5d8d8654eb1f4bf1f20cbbb

Tree-SHA512: 94a2cedb132db457b67b3c60cde8843d9db1d2bc8dba0530cd5c518ebed955bd66a1649c61e0cb96b6f293ce6b9b0395582877ce9f1de003e0020a66100d172f

Author: william2332-limf

api/all-features.txt

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# Checks the public API of crates, exits with non-zero if there are currently
+# changes to the public API not already committed to in the various api/*.txt
+# files.
+
+set -e
+
+export RUSTDOCFLAGS='-A rustdoc::broken-intra-doc-links'
+REPO_DIR=$(git rev-parse --show-toplevel)
+API_DIR="$REPO_DIR/api"
+CMD="cargo +nightly public-api --simplified"
+
+# cargo public-api uses nightly so the toolchain must be available.
+if ! cargo +nightly --version > /dev/null; then
+    echo "script requires a nightly toolchain to be installed (possibly >= nightly-2023-05-24)" >&2
+    exit 1
+fi
+
+pushd "$REPO_DIR" > /dev/null
+$CMD --no-default-features | sort --unique > "$API_DIR/no-default-features.txt"
+$CMD --no-default-features --features=alloc | sort --unique > "$API_DIR/alloc.txt"
+$CMD | sort --unique > "$API_DIR/default-features.txt"
+$CMD --features=global-context | sort --unique > "$API_DIR/global-context.txt"
+$CMD --all-features | sort --unique > "$API_DIR/all-features.txt"
+
+if [[ $(git status --porcelain api) ]]; then
+    echo "You have introduced changes to the public API, commit the changes to api/ currently in your working directory" >&2
+else
+    echo "No changes to the current public API"
+fi
+popd > /dev/null