Sitelet https://github.com/SharkHand3/examples/commit/d1251c618ff9fc4d3f58c6d9be2cfa9dbd5fdea2
Skip to content

Commit d1251c6

Browse files
mattssemattsse
authored
feat(examples): add validated example catalog (alloy-rs#251)
* feat(examples): add validated example catalog * fix(examples): classify runtime requirements accurately * fix(examples): correct network overrides
1 parent 611cab0 commit d1251c6

14 files changed

Lines changed: 2469 additions & 29 deletions

File tree

‎.github/workflows/test.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ jobs:
5151
- uses: Swatinem/rust-cache@v2
5252
with:
5353
cache-on-failure: true
54+
- name: Check example index
55+
run: python3 scripts/generate-example-index.py --check
5456
- name: cargo hack
5557
run: cargo hack check --feature-powerset --depth 2 --locked
5658

‎AGENTS.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Alloy examples agent guide
2+
3+
Use `examples-index.json` as the first lookup surface. It lists every Cargo example target with its
4+
source path, summary, exact run command, and structured runtime requirements. Filter the `runtime`
5+
object before selecting an example; do not assume network access, credentials, node binaries, or
6+
hardware are available.
7+
8+
Source-of-truth order:
9+
10+
1. `Cargo.toml` and the package manifests define dependency and feature behavior.
11+
2. `examples-index.json` maps tasks to runnable targets and prerequisites.
12+
3. The referenced Rust source is authoritative for the API usage.
13+
4. `README.md` is the human-oriented overview.
14+
15+
When adding or renaming an example:
16+
17+
1. Start the source file with a concise `//!` summary.
18+
2. Add it to `README.md`.
19+
3. Add only deterministic, offline examples to `scripts/runtime-examples.txt`.
20+
4. Run `python3 scripts/generate-example-index.py` and commit the updated index.
21+
5. Run `cargo check --workspace --examples --all-features --locked`.
22+
23+
Do not add shared public RPC endpoints or placeholder credentials. Use the helpers in
24+
`example-support` so missing configuration produces an actionable error. Keep helper modules under
25+
a named example directory so Cargo does not expose them as accidental example targets.

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -128,12 +128,14 @@ less work from you.
128128
This section lists some commonly needed commands.
129129

130130
```sh
131-
cargo check --examples --all-features
132-
cargo build --examples --all-features
133-
cargo +nightly fmt --all
131+
cargo check --workspace --examples --all-features --locked
132+
cargo build --workspace --examples --all-features --locked
133+
cargo +nightly fmt --all --check
134134
cargo +nightly clippy \
135+
--workspace \
135136
--examples \
136137
--all-features \
138+
--locked \
137139
-- -D warnings
138140
```
139141

@@ -149,6 +151,15 @@ To run all (runnable) examples:
149151
./scripts/test.sh
150152
```
151153

154+
When adding or renaming an example, give it a leading `//!` summary, add it to `README.md`, and run:
155+
156+
```sh
157+
python3 scripts/generate-example-index.py
158+
```
159+
160+
Commit the updated `examples-index.json`. Add an example to `scripts/runtime-examples.txt` only when
161+
it is deterministic and requires no network service, node process, credentials, or hardware.
162+
152163
### Tests
153164

154165
If the change being proposed alters code (as opposed to only documentation for

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ Examples that fork a network also require [`anvil`](https://getfoundry.sh/anvil/
3737
`PATH`. Hardware-wallet and cloud-signer examples require the device or credentials described in
3838
their source code.
3939

40+
For programmatic discovery, [`examples-index.json`](./examples-index.json) lists every example with
41+
its summary, source path, exact command, network, environment variables, binaries, services, and
42+
hardware requirements. The index is generated from Cargo metadata and the example source files.
43+
4044
## Overview
4145

4246
This repository contains the following examples:
@@ -127,6 +131,7 @@ This repository contains the following examples:
127131
- [x] [Event multiplexer](./examples/subscriptions/examples/event_multiplexer.rs)
128132
- [x] Transactions
129133
- [x] [Decode input](./examples/transactions/examples/decode_input.rs)
134+
- [x] [Decode a receipt log](./examples/transactions/examples/decode_receipt_log.rs)
130135
- [x] [Encode and decode EIP-1559 transaction](./examples/transactions/examples/encode_decode_eip1559.rs)
131136
- [x] [Get gas price in USD](./examples/transactions/examples/gas_price_usd.rs)
132137
- [x] [Simulate using `debug_traceCallMany`](./examples/transactions/examples/debug_trace_call_many.rs)

0 commit comments

Comments
 (0)