# Distribution

This directory is the sharing kit for the current `rscrypto` 0.3 release line. Each file is one channel or one piece of supporting research; together they are the operational playbook for turning the README into public posts that technical readers can trust.

The animating idea: **crypto should not be the place your Rust project stops being portable.** Every piece of copy in here is built to make that point land with a specific audience.

---

## Files in this directory

| File | What it is |
|---|---|
| [`README.md`](README.md) | This index — sharing sequence, voice rules, claims sheet. |
| [`hacker-news.md`](hacker-news.md) | Show HN title options, first comment, pre-prepared replies, submission mechanics. |
| [`reddit.md`](reddit.md) | r/rust title and post body, replies for common questions, other-subreddit guidance. |
| [`rust-forum.md`](rust-forum.md) | Rust Users Forum announcement post, tone rules. |
| [`devto-article.md`](devto-article.md) | Long-form launch article with front matter, body, follow-up series plan. |
| [`social.md`](social.md) | X thread, Mastodon, Bluesky, Threads, LinkedIn — built on open-source X-algorithm research. |
| [`../migration/README.md`](../migration/README.md) | Migration starters from RustCrypto, `blake3`, CRC crates, fast hashes, AEADs, signatures, and password hashing. |
| [`visuals.md`](visuals.md) | Production manifest for every image, chart, and the demo video. |
| [`case-studies.md`](case-studies.md) | Research layer — what worked for comparable launches and why. |

---

## Sharing Sequence

Strict ordering. Each step assumes the previous one succeeded.

1. **Confirm green CI.** `ci.yaml` should be green for the exact commit you are about to share. `weekly.yaml` should not have an unresolved security or fuzz failure.
2. **Verify the public surface.** README, docs.rs, crates.io, [`docs/migration/`](../migration/README.md), and [`benchmark_results/OVERVIEW.md`](../../benchmark_results/OVERVIEW.md) must be live and internally consistent.
3. **Produce only the assets you will actually attach.** Walk [`visuals.md`](visuals.md). If the platform card is missing, use the text-only variants instead of shipping a broken image link.
4. **Set the DEV canonical URL.** Use the GitHub Release URL unless Discussions are enabled. If Discussions are later enabled, create "rscrypto 0.3 — pure-Rust crypto across six architecture families" in Announcements and pin it.
5. **Post the Rust Users Forum announcement.** See [`rust-forum.md`](rust-forum.md). Forum posts age the longest; this becomes the durable technical reference.
6. **Post r/rust.** See [`reddit.md`](reddit.md). Block out 90 minutes for replies.
7. **Submit Hacker News** only after the README, docs.rs, benchmarks, and migration guides are live. Link the GitHub README or the DEV article. See [`hacker-news.md`](hacker-news.md). Block out 4 hours.
8. **Post the X thread** with the platform-matrix card attached if it exists. See [`social.md`](social.md). Block out 60 minutes for replies.
9. **Cross-post Mastodon, Bluesky, Threads, LinkedIn.** Same day or next day; not all at once. Use the per-platform copy in [`social.md`](social.md), not the X copy verbatim.
10. **Publish the DEV article.** Schedule for Tue/Wed morning US Eastern. Set `canonical_url` to the GitHub Discussion from step 4 if you opened one.
11. **Spend a week answering technical criticism.** File issues for concrete feedback; do not repeat promotional posts.

A reasonable timeline: Day 1 = CI, docs, migration links, assets, discussion. Day 2 = forum + r/rust. Day 3 = HN. Day 4 = social and DEV. Days 5–14 = reply, file issues, write follow-up notes.

**What never to do during sharing week**: edit the README materially after people start linking it, change crates.io metadata mid-thread, or post unrelated project updates. Every signal a reader sees should reinforce the same 0.3-line story.

---

## Voice Rules (applies to every channel)

- **First-person, present-tense.** "I built rscrypto because…" — not "rscrypto is a single-crate stack that…" Pick "I" or "we" once and hold it across every piece.
- **Numbers are scenes, not stats.** "**3,545 wins and 5,210 wins-or-ties out of 5,832 fastest-external Linux CI comparisons**" is a verdict. "**235 wins and 450 wins-or-ties out of 463 MBP M1 fastest-external comparisons**" is a second, platform-specific scene. "1.61x geomean" alone is a stat line. Always pair the number with what it's measuring.
- **Hedges are honesty, not defense.** "Not FIPS validated. Not a TLS stack. Not a request to replace mature crypto in production." Stating the limits before someone asks signals confidence, not weakness.
- **Specific verbs, not adjectives.** "Benchmarked across nine Linux runners" beats "extensively tested." "Differential-tested against the portable path on every CI run" beats "robust."
- **Acknowledge IBM and RISE in the main copy.** They opened POWER10 / IBM Z / RISC-V runner access. Without those partnerships the s390x, ppc64le, and riscv64 backends do not exist for a single-maintainer crate. Don't bury this in a footnote.
- **No superlatives without numbers adjacent.** "Fastest" by itself is suspect. "1.61x Linux CI geomean and 1.25x Apple Silicon geomean against the fastest matched Rust baselines" is a claim.
- **Never say "canonical" in public copy.** That's the ambition, not the proof. Let users reach the conclusion.

---

## Claims Sheet

Use only claims backed by [`benchmark_results/OVERVIEW.md`](../../benchmark_results/OVERVIEW.md), recomputed from the 2026-05-27 Linux CI pass and the 2026-06-01 Apple Silicon local full run.

### Safe to use

| Claim | Safe wording |
|---|---|
| Linux headline | "3,545 wins and 5,210 wins-or-ties out of 5,832 fastest-external Linux CI comparisons, with a 1.61× geomean against the fastest matched Rust baseline." |
| Apple Silicon headline | "On a local MBP M1 macOS/aarch64 full run, 235 wins and 450 wins-or-ties out of 463 fastest-external comparisons, with a 1.25× geomean against the fastest matched Rust baseline." |
| BLAKE3 | "2.31× geomean faster than the `blake3` crate on Linux CI one-shot/keyed/derive-key inputs ≥ 64 KiB. Tiny inputs and some platforms are closer." |
| Checksums | "5.03× geomean across Linux CI fastest-external checksum comparisons." |
| AEAD | "1.57× geomean across Linux CI fastest-external AEAD comparisons; GCM-SIV, XChaCha20-Poly1305, AEGIS-256, and IBM Z are the strongest areas." |
| SHA-3 / SHAKE | "2.15× / 1.86× geomean vs RustCrypto `sha3` on Linux CI fastest-external comparisons." |
| RSA | "RSA import plus verification is 1.32× geomean with 75 wins out of 99 fastest-external RSA comparisons, but verification-only is 0.98×; do not hide that split." |
| Ed25519 / X25519 | "Do not lead with public-key speed claims: Linux CI Ed25519 verify is 1.00× and X25519 is 0.95× fastest-external geomean." |
| Apple Silicon category claims | "Apple Silicon MBP M1 fastest-external geomeans: checksums 2.76×, AEAD 1.47×, RSA import plus verification 1.45×, RSA verification-only 1.19×, BLAKE3 ≥64 KiB 1.80×. SHA-3 is below parity at 0.94× while SHAKE remains positive at 1.32×; say that plainly." |
| Platform reach | "Nine measured Linux CI runners: Intel Sapphire Rapids, Intel Ice Lake, AMD Zen4, AMD Zen5, AWS Graviton3, AWS Graviton4, IBM Z, IBM POWER10, RISE RISC-V; plus a local Apple Silicon MBP M1 full run." |
| Coverage boundary | "The 2026-05-27 Linux CI run omits Argon2, scrypt, and Ascon-AEAD; the 2026-06-01 Apple Silicon run includes them. Do not merge the totals because the commits and scopes differ." |
| Dependency story | "Zero default dependencies. The `full` primitive stack does not pull OpenSSL, C FFI, RustCrypto, dalek, blake3, or any `crc-*` crate. Optional `getrandom`, `serde`, and `rayon` are opt-in via named features." |
| Trust model | "Portable Rust is the byte-for-byte authority. Every SIMD or ASM kernel is differential-tested against the portable path on every CI run; mismatch fails the build." |
| Migration story | "Migration guides cover 28 source crates across checksums, hashes, auth, AEADs, signatures/KEX, and password hashing: `docs/migration/`." |

### Never use

| Forbidden claim | Why |
|---|---|
| "Drop-in RustCrypto replacement" | The APIs are intentionally not identical. |
| "FIPS validated" | Not a validated module. Say "FIPS-aligned primitives" or "FIPS-oriented building blocks." |
| "Always faster" / "Universally faster" | The benchmark data has ties and losses, especially PBKDF2-SHA256 `iters=1`, X25519 DH, RSA verification on Arm/RISC-V, and small-message AEAD rows. |
| "Zero dependencies" (no qualifier) | Qualify: "zero default dependencies" or "zero dependencies for the `full` primitive stack." Optional `getrandom` / `serde` / `rayon` exist. |
| "Audited" | Not yet — third-party audit is on the roadmap before 1.0. |
| "Production-ready" | Say "production-quality algorithms and platform backends" if you must. The 0.3 line is still pre-1.0. |
| "Canonical Rust crypto library" | This is the ambition. Public copy must let the conclusion be reached, not asserted. |
| "Bulletproof," "blazing," "unbreakable," "military-grade" | Auto-flags every skeptical reader on every platform. |

---

## What "different per channel" actually means

The same release story speaks to three audiences with different expectations:

- **HN** wants a falsifiable artifact and a respectful first comment that names the limits before critics do. Long lists of features fail. Specific numbers + reproduction path + invite-the-criticism tone wins.
- **r/rust** wants a Rust-specific release note with the feature shape, MSRV, the trade vs. the ecosystem, and a real OP who answers comments. Promotional tone fails. Useful prose with code blocks wins.
- **The Rust Users Forum** wants engineering notes — MSRV, edition, feature flags, breaking-change policy, audit status — in a calm voice that invites API and unsafe review. Energetic launch tone fails. "Published, with the following caveats" wins.
- **DEV / long-form** wants the story behind the artifact. Release-note shape fails. A narrative with one chart, one diagram, one before/after, and the explicit limits wins.
- **X / social** wants one quotable line and one image. Multi-line bullet lists fail. A single specific claim, one image, one closing question that triggers replies wins.
- **LinkedIn** wants the supply-chain / professional framing, longer text, link in the first comment.

Don't paste the same copy across channels. Each file in this directory is calibrated to its audience.

---

## Research Layer

The empirical research that informs this playbook lives in:

- [`case-studies.md`](case-studies.md) — what worked for comparable launches (BLAKE3, Lucebox/Megakernel, RustCrypto crypto-bigint, OpenClaw, MiroFish, RTK), what failed, and why.
- The X thread tactics in [`social.md`](social.md) are derived from a code-level read of the open-source [`twitter/the-algorithm`](https://github.com/twitter/the-algorithm) heavy ranker (reply-weight, OON SimCluster routing, AuthorDiversity caps).
- Hacker News and Reddit guidance is calibrated against documented community guidelines and the comparable-launch lessons in `case-studies.md`. (Live HN-Algolia / Reddit-JSON empirical data was not collected for this sharing kit; if you re-run the research with web access, the case-studies file is the right place to integrate new findings.)

---

## Source Links

Channel guidance was checked against current public documents at the time of writing.

- Hacker News Guidelines: https://news.ycombinator.com/newsguidelines.html
- Reddit content policy: https://www.redditinc.com/policies/content-policy
- r/rust rules archive: https://archive.ph/2026.01.11-033232/https://www.reddit.com/r/rust/wiki/rules
- Rust Users Forum announcements: https://users.rust-lang.org/c/announcements/6
- DEV writing guidance: https://dev.to/help/writing-editing-scheduling
- DEV high-quality post guidance: https://dev.to/devteam/how-to-write-a-high-quality-post-on-dev-3me0
- X rate limits: https://help.x.com/en/rules-and-policies/x-limits
- X / Twitter open-source algorithm: https://github.com/twitter/the-algorithm and https://github.com/twitter/the-algorithm-ml
- Rust API Guidelines (release-note guidance): https://rust-lang.github.io/api-guidelines/documentation.html
- Lib.rs ranking signals: https://lib.rs/about

The case-studies file ([`case-studies.md`](case-studies.md)) cites primary HN threads, GitHub repos, and Rust forum posts for every borrowed pattern.
