What changed, and why it matters
This commit simply reorganizes project documentation. It moves contributor and maintainer instructions from the main README file into the CONTRIBUTING guide, and adds a short section about no-std support to the README. No program code was changed, so this cannot affect security.
No security action needed. Treat as a normal documentation cleanup.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is limited to markdown documentation files (CONTRIBUTING.md and README.md). Content describing how to install Rust, build the project, run tests, use development tools, and the contribution workflow is moved from README.md into CONTRIBUTING.md. A ‘No-std support’ section is added to README.md. There are no source-code, build-script, dependency, or configuration changes.
Changed components
Inspect captured patch +102 / −101
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3dc1021a..c71b4509 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,6 +13,13 @@ changes to this document in a pull request.
- [General](#general)
- [Communication channels](#communication-channels)
- [Asking questions](#asking-questions)
+- [Getting Started](#getting-started)
+ * [Installing Rust](#installing-rust)
+ * [Building](#building)
+- [Development Tools](#development-tools)
+ * [Just](#just)
+ * [Githooks](#githooks)
+ * [Building the docs](#building-the-docs)
- [Contribution workflow](#contribution-workflow)
* [Preparing PRs](#preparing-prs)
* [Peer review](#peer-review)
@@ -25,6 +32,10 @@ changes to this document in a pull request.
* [Policy](#policy)
- [Security](#security)
- [Testing](#testing)
+ * [Unit/Integration tests](#unitintegration-tests)
+ * [Benchmarks](#benchmarks)
+ * [Mutation tests](#mutation-tests)
+ * [Code verification](#code-verification)
- [Going further](#going-further)
@@ -68,6 +79,58 @@ We have a dedicated developer channel on IRC, #bitcoin-rust@libera.chat where
you may get helpful advice if you have questions.
+## Getting Started
+
+### Installing Rust
+
+Rust can be installed using your package manager of choice or [rustup.rs](https://rustup.rs). The
+former way is considered more secure since it typically doesn't involve trust in the CA system. But
+you should be aware that the version of Rust shipped by your distribution might be out of date.
+Generally this isn't a problem for `rust-bitcoin` since we support much older versions than the
+current stable one (see MSRV section in [README.md](./README.md)).
+
+### Building
+
+The library can be built and tested using [`cargo`](https://github.com/rust-lang/cargo/):
+
+```
+git clone git@github.com:rust-bitcoin/rust-bitcoin.git
+cd rust-bitcoin
+cargo build
+```
+
+You can run tests with:
+
+```
+cargo test
+```
+
+Please refer to the [`cargo` documentation](https://doc.rust-lang.org/stable/cargo/) for more
+detailed instructions.
+
+
+## Development Tools
+
+### Just
+
+We support [`just`](https://just.systems/man/en/) for running dev workflow commands. Run `just` from
+your shell to see a list of available sub-commands.
+
+### Githooks
+
+To assist devs in catching errors _before_ running CI we provide some githooks. Copy the hooks in `githooks/`
+to your githooks folder or run `just githooks-install` to copy them all.
+
+### Building the docs
+
+We build docs with the nightly toolchain, you may wish to use the following shell alias to check
+your documentation changes build correctly.
+
+```
+alias build-docs='RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --features="$FEATURES" -- -D rustdoc::broken-intra-doc-links'
+```
+
+
## Contribution workflow
The codebase is maintained using the "contributor workflow" where everyone
@@ -248,8 +311,36 @@ seriously. Due to the modular nature of the project, writing new test cases is
easy and good test coverage of the codebase is an important goal. Refactoring
the project to enable fine-grained unit testing is also an ongoing effort.
-Various methods of testing are in use (e.g. fuzzing, mutation), please see
-the [readme](./README.md) for more information.
+Unit and integration tests are available for those interested, along with benchmarks. For project
+developers, especially new contributors looking for something to work on, we do:
+
+- Fuzz testing with [`Honggfuzz`](https://github.com/rust-fuzz/honggfuzz-rs)
+- Mutation testing with [`cargo-mutants`](https://github.com/sourcefrog/cargo-mutants)
+- Code verification with [`Kani`](https://github.com/model-checking/kani)
+
+There are always more tests to write and more bugs to find. PRs are extremely welcomed.
+Please consider testing code as a first-class citizen. We definitely do take PRs
+improving and cleaning up test code.
+
+### Unit/Integration tests
+
+Run as for any other Rust project `cargo test --all-features`.
+
+### Benchmarks
+
+We use a custom Rust compiler configuration conditional to guard the bench mark code. To run the
+bench marks use: `RUSTFLAGS='--cfg=bench' cargo +nightly bench`.
+
+### Mutation tests
+
+We are doing mutation testing with [cargo-mutants](https://github.com/sourcefrog/cargo-mutants). To run
+these tests first install with `cargo install --locked cargo-mutants` then run with `cargo mutants --in-place --no-shuffle`.
+Note that running these mutation tests will take on the order of 10's of minutes.
+
+### Code verification
+
+We have started using [kani](https://github.com/model-checking/kani), install with `cargo install --locked kani-verifier`
+ (no need to run `cargo kani setup`). Run the tests with `cargo kani`.
## LLMs, GitHub bot accounts, and AI agents
diff --git a/README.md b/README.md
index 1b7fc876..3037176a 100644
--- a/README.md
+++ b/README.md
@@ -80,6 +80,15 @@ This library should compile with any combination of features on **Rust 1.74.0**.
Use `Cargo-minimal.lock` to build the MSRV by copying to `Cargo.lock` and building.
+## No-std support
+
+The `std` cargo feature is enabled by default. To build this project without the Rust standard
+library, use the `--no-default-features` flag or set `default-features = false` in your dependency
+declaration when adding it to your project.
+
+For embedded device examples, see [`bitcoin/embedded`](https://github.com/rust-bitcoin/rust-bitcoin/tree/master/bitcoin/embedded)
+or [`hashes/embedded`](https://github.com/rust-bitcoin/rust-bitcoin/tree/master/hashes/embedded).
+
## External dependencies
We integrate with a few external libraries, most notably `serde`. These
@@ -93,105 +102,6 @@ of "our CI didn't fail with these versions". Specifically, we do not guarantee
that the committed hashes are free from malware. It is your responsibility to
review them.
-## Installing Rust
-
-Rust can be installed using your package manager of choice or [rustup.rs](https://rustup.rs). The
-former way is considered more secure since it typically doesn't involve trust in the CA system. But
-you should be aware that the version of Rust shipped by your distribution might be out of date.
-Generally this isn't a problem for `rust-bitcoin` since we support much older versions than the
-current stable one (see MSRV section).
-
-## Building
-
-The library can be built and tested using [`cargo`](https://github.com/rust-lang/cargo/):
-
-```
-git clone git@github.com:rust-bitcoin/rust-bitcoin.git
-cd rust-bitcoin
-cargo build
-```
-
-You can run tests with:
-
-```
-cargo test
-```
-
-Please refer to the [`cargo` documentation](https://doc.rust-lang.org/stable/cargo/) for more
-detailed instructions.
-
-### No-std support
-
-The `std` cargo feature is enabled by default. To build this project without the Rust standard
-library, use the `--no-default-features` flag or set `default-features = false` in your dependency
-declaration when adding it to your project.
-
-For embedded device examples, see [`bitcoin/embedded`](https://github.com/rust-bitcoin/rust-bitcoin/tree/master/bitcoin/embedded)
-or [`hashes/embedded`](https://github.com/rust-bitcoin/rust-bitcoin/tree/master/hashes/embedded).
-
-### Just
-
-We support [`just`](https://just.systems/man/en/) for running dev workflow commands. Run `just` from
-your shell to see a list of available sub-commands.
-
-### Building the docs
-
-We build docs with the nightly toolchain, you may wish to use the following shell alias to check
-your documentation changes build correctly.
-
-```
-alias build-docs='RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --features="$FEATURES" -- -D rustdoc::broken-intra-doc-links'
-```
-
-## Testing
-
-Unit and integration tests are available for those interested, along with benchmarks. For project
-developers, especially new contributors looking for something to work on, we do:
-
-- Fuzz testing with [`Honggfuzz`](https://github.com/rust-fuzz/honggfuzz-rs)
-- Mutation testing with [`cargo-mutants`](https://github.com/sourcefrog/cargo-mutants)
-- Code verification with [`Kani`](https://github.com/model-checking/kani)
-
-There are always more tests to write and more bugs to find. PRs are extremely welcomed.
-Please consider testing code as a first-class citizen. We definitely do take PRs
-improving and cleaning up test code.
-
-### Unit/Integration tests
-
-Run as for any other Rust project `cargo test --all-features`.
-
-### Benchmarks
-
-We use a custom Rust compiler configuration conditional to guard the bench mark code. To run the
-bench marks use: `RUSTFLAGS='--cfg=bench' cargo +nightly bench`.
-
-### Mutation tests
-
-We are doing mutation testing with [cargo-mutants](https://github.com/sourcefrog/cargo-mutants). To run
-these tests first install with `cargo install --locked cargo-mutants` then run with `cargo mutants --in-place --no-shuffle`.
-Note that running these mutation tests will take on the order of 10's of minutes.
-
-### Code verification
-
-We have started using [kani](https://github.com/model-checking/kani), install with `cargo install --locked kani-verifier`
- (no need to run `cargo kani setup`). Run the tests with `cargo kani`.
-
-## Pull Requests
-
-Every PR needs at least two reviews to get merged. During the review phase, maintainers and
-contributors are likely to leave comments and request changes. Please try to address them, otherwise
-your PR might get closed without merging after a longer time of inactivity. If your PR isn't ready
-for review yet please mark it by prefixing the title with `WIP: `.
-
-### CI Pipeline
-
-The CI pipeline requires approval before being run on each PR.
-
-### Githooks
-
-To assist devs in catching errors _before_ running CI we provide some githooks. Copy the hooks in `githooks/`
-to your githooks folder or run `just githooks-install` to copy them all.
-
## Policy on Altcoins/Altchains
Since the altcoin landscape includes projects which [frequently appear and disappear, and are poorly
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.