Thanks for helping. This file covers the mechanics; read docs/ARCHITECTURE_OVERVIEW.md before changing anything non-trivial, and its "Where to look" table to find the right module.
Search existing issues first. Include what you ran, what you expected, what happened, the crate version or commit, and your OS and Rust version. Redact account hashes, tokens and app keys from logs. Report security problems privately rather than in a public issue.
Rust 1.89 or newer (edition 2024; the MSRV). rust-toolchain.toml pins the
toolchain CI and releases build with, and rustup installs it on first use.
SQLite is bundled. Fuzzing needs a nightly toolchain and cargo-fuzz.
git clone <repository-url>
cd rustyschwab
cargo build --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-featuresExamples are workspace packages, so run them with -p:
cp .env.example .env # then fill in SCHWAB_APP_KEY / SCHWAB_APP_SECRET
cargo run -p oauth-flow
cargo run -p comprehensive
cargo run -p streaming-examples --bin streaming_quotesRun what CI runs (.github/workflows/ci.yml):
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo doc --workspace --no-deps --all-features --locked
cargo build --workspace --all-targets --locked
cargo test --workspace --all-targets --all-features --locked
cargo test --workspace --doc --all-features --locked
cargo check -p rustyschwab --no-default-features --locked
cargo check -p rustyschwab --no-default-features --features native-tls --locked
cargo check -p rustyschwab --no-default-features --features callback-server --locked
cargo check -p rustyschwab-types --no-default-features --locked
cargo package -p rustyschwab-types -p rustyschwab -p rustyschwab-mcp -p rustyschwab-console -p rustyschwab-dash --locked
cargo deny check advisories bans licenses sources
cargo machete # unused dependencies
actionlint # when you change .github/workflowsUntrusted-input decoders have fuzz targets (fuzz/): run one with
cd fuzz && cargo +nightly fuzz run order_request -- -max_total_time=60
when you change a decoder or validator, and add a target for a new one.
The two cargo test lines are both needed: --all-targets skips doctests.
CI additionally tests on the MSRV, checks every SDK feature on its own
(cargo hack), checks that a native-tls build carries no rustls, holds
line coverage at or above its floor (cargo llvm-cov), runs each fuzz
target briefly, compares the public API against the base branch with
cargo-semver-checks, and runs the stream soak harness. The security
workflow scans for advisories daily, for verified secrets and with CodeQL
on every change, and records an OpenSSF Scorecard; a weekly workflow fuzzes
for longer, runs mutation testing over risk, execution and reconciliation,
and builds against minimal dependency versions. Intentional public-API
breaks need a CHANGELOG entry with migration notes.
Protect main by requiring the CI and Security checks to pass before a
merge (the rustfmt, clippy, rustdoc, test, SDK feature combinations, coverage, unused dependencies, fuzz smoke,
publishable crates, cargo deny and workflow lint jobs, the python
matrix, compatibility (the semver check, on pull requests) and soak,
plus secret scan and CodeQL).
Then:
-
Add or update tests. Wire-shape changes need a fixture or
wiremocktest; decoding changes should keepcrates/rustyschwab-types/tests/properties.rs(no panic on arbitrary input) passing. If you have Schwab credentials, also run the read-only live sweep so the typed bindings are checked against the real API:SCHWAB_LIVE_CONFORMANCE=1 cargo test -p rustyschwab --test live_conformance -- --nocaptureIt only issues
GETs.SCHWAB_LIVE_CONFORMANCE=recordrefreshescrates/rustyschwab/tests/fixtures/conformance/; commit the fixture diff with the change that explains it. -
Add a line under
## [Unreleased]inCHANGELOG.md(Keep a Changelog format). -
Update
.env.exampleif you add or rename aSCHWAB_*variable. If you add or remove an MCP tool, updateEXPECTED_TOOLSincrates/rustyschwab-mcp/tests/tool_inventory.rsand the tool catalog indocs/MCP_LLM_INTEGRATION.md; the test checks both. -
Keep commits focused; one concern per commit.
rustfmt and clippy -D warnings are the style guide. Beyond that:
- Prefer typed fields over
String/Value; if Schwab's shape is uncertain, say so in a comment and keep the tolerant type on the response side only. - Errors go through
rustyschwab::Error; add a variant rather than stringly errors, and setErrorKind/is_retryablecorrectly. - Every metric is declared in
metrics.rswith its label set; do not emit ad-hoc names. - Anything that touches submissions must keep the never-replay rule and the
journal
begin_once/finishpairing. - Public items carry doc comments; doc examples must compile and pass
cargo test --doc. - Doc-comment markdown tables (the metric catalogs in
metrics.rs) and SQL migration literals (storage.rs) run past 100 columns on purpose: a table row cannot wrap and stay a row, and rustfmt leaves comments and string literals alone (wrap_comments/format_stringsstay off, anderror_on_line_overflowis not enabled). Do not reflow them.
Conventional commit style: type(scope): summary, where type is one of
feat, fix, docs, refactor, test, chore, perf, ci. The body
explains why, not what.
- Bump the version in the workspace
Cargo.toml, the internal path dependencies andcrates/schwab-py/Cargo.tomltogether. - Move the
[Unreleased]section inCHANGELOG.mdto a dated version. - Tag
vX.Y.Zon amaincommit that passed CI, and push the tag.release.ymltests the tag, builds the binaries, an SBOM and a provenance attestation, and drafts a GitHub Release with them; review and publish it. Verify an artifact withgh attestation verify <file> --repo Epistates/rustyschwab. - Run
publish.ymlfor the tag. After approval in thecrates-ioenvironment it checks that CI andrelease.ymlpassed on the tagged commit, packages the five crates, and publishes them in dependency order through crates.io trusted publishing. - The same tag push starts
publish-python.yml, which builds therustyschwababi3 wheels and sdist, tests the Linux wheel, and after approval in thepypienvironment (and the same check) publishes them through PyPI trusted publishing. Run it by hand before tagging to inspect the artifacts without publishing.
See docs/RELEASING.md for the full checklist and docs/SUPPORT.md for the compatibility policy.