docs(stripe): say why async-stripe is pinned to a candidate

[productdevbook]

Closes #11.

#11 asked whether =1.0.0-rc.8 should still be the pin. Checked rather than
assumed, on 2026-08-14. The answer is yes, and the deliverable is the answer
written down where it will be read.

What upstream has done since rc.8

Nothing that reaches this crate.

• https://index.crates.io/as/yn/async-stripe ends at 1.0.0-rc.8, published
  2026-08-05T15:54:50Z. async-stripe-core, -shared and -types end at
  the same version. There is no 1.0.0, no 1.0.0-rc.9.
• rc.9 exists only as arlyon/async-stripe#948, release-plz's standing
  release PR, opened 2026-08-05T15:57 and last touched 2026-08-05T16:02. Every
  crate's changelog entry in it reads Other: release v1.0.0-rc.8 — it is
  version-bump bookkeeping with no functional change behind it.
• async-stripe-v1.0.0-rc.8...master is three commits ahead and all fifteen
  changed files are CHANGELOG.md. Not one line of Rust has moved upstream
  since the release.
• No milestone, roadmap issue or announcement for 1.0.0 final. The open issues
  are eight, the newest being a stack overflow in
  EventObject::from_raw_data on rc.8 — the webhook parser, which this crate
  does not use.

So the cost of upgrading is not "small". There is nothing to upgrade to.

Why the pin stays exact

A candidate is not additive in the modules this crate builds on.

step	Rust files changed	what it did to us
rc.6 → rc.7	265	payment_intent/requests.rs +2031/-179; stripe_shared::PaymentIntent gained a public field allowed_payment_method_types — a struct-literal break for anyone constructing one
rc.7 → rc.8	1	the client's retry strategy

Upstream's own README pins the same way — async-stripe = "=1.0.0-rc.5",
itself three candidates behind what they have released. The practice is the
recommendation there; the number is not.

The looser middle was considered and is worse than either end. A caret
requirement on a prerelease ("1.0.0-rc.8") admits rc.9…rc.N and 1.0.0
alike, so it relaxes the half that can break silently in someone else's build
while buying nothing a released 1.0.0 would not buy anyway. >=rc.8, <1.0.0
is the same trade with the upside removed.

What is in the diff

The constraint is caller-visible and 0.0.1 shipped without saying it, so:

• crates/kasapay-stripe/src/lib.rs — a Which async-stripe section: the
  version, why it is pinned, and what it costs (a crate depending on
  async-stripe itself must be on the same candidate, because two exact pins
  at different candidates do not resolve together; Stripe::client is there so
  that reaching past what this crate models needs no second dependency).
• Cargo.toml — the comment over the four pins now says what would change it,
  and is a line shorter than what it replaces.
• CHANGELOG.md — the same, under Unreleased, for whoever upgrades.

No version was changed, so nothing here can break a build. The next move is
upstream's: 1.0.0 ships, the pin becomes a range, and that is a release.

🤖 Generated with Claude Code