Totoro-jam/battle-tested-patterns

This is an open, ongoing invitation: improve the depth and quality of any pattern's content, in whatever direction you think matters most. We don't prescribe the shape. What we care about is that your PR makes the content meaningfully better and comes with enough reasoning and evidence to be convincing. Possible directions (non-exhaustive): Explanation — clearer mental model, better "why it works", failure modes Exercises — stronger edge cases, more realistic scenarios Challenge Questions — deeper, more thought-provoking Q&A Production proof — more accurate / better-sourced real-world links (SHA permalink + line range, HTTP 200) Diagrams — clearer visuals (mermaid welcome) Multilingual — better phrasing / consistency across EN & ZH What we expect from your PR A short rationale: what you're improving, why it matters, and what evidence backs it (a source link, a benchmark, a reference, a clear argument) Keep EN/ZH in sync; pass the existing checks (pnpm check) It's fine to

Pick a pattern's ZH doc and improve translation quality (natural phrasing, term consistency) while keeping structure and code blocks byte-identical to the EN version. Scope Edit docs/zh/patterns/<name>/index.md Keep structure/headings/code blocks byte-identical to docs/patterns/<name>/index.md (our parity check enforces this) How to verify pnpm check:content # confirms EN/ZH parity pnpm dev # preview the rendered ZH page locally Why this is a good first issue Native-speaker friendly, scoped to one file, the parity check guards correctness. See CONTRIBUTING → Good First Contributions.

Every source link in a pattern doc points to a SHA permalink + line range. Over time the code at that line range can drift. We have tooling to detect it. Scope Run the verifier, review any reported drift, and fix the line range or SHA if needed Even if nothing needs fixing, reporting "all clean" is a valid contribution How to verify pnpm verify-lines # checks code at each link's line range still matches (needs network) Why this is a good first issue The tooling does the detection — the contributor just confirms or fixes. Teaches our core differentiator. See CONTRIBUTING → Source Link Requirements.

The docs/by-project/ pages map patterns to real systems (React, Linux, Go, Git, Node.js, Rust, game engines, distributed systems). Pick a project page and add one well-sourced example linking a pattern to a specific production code location. Scope Edit a page under docs/by-project/ (and keep docs/zh/by-project/ in sync) The source link MUST follow our rules: SHA permalink + line range (e.g. .../blob/<sha>/path#L18-L22), returns HTTP 200, not a branch link, not a directory How to verify pnpm verify-links # checks source URLs return HTTP 200 (needs network) pnpm check:content # confirms EN/ZH parity Why this is a good first issue Research-oriented, one entry, reinforces our core "verifiable source" standard. See CONTRIBUTING → Source Link Requirements.

Each pattern has exercises in 4 languages (TypeScript, Rust, Go, Python). Pick a pattern and add one new edge-case test scenario (e.g. empty input, boundary value, concurrent access) to its existing exercise. Scope Add the test scenario to the exercise (start with TypeScript under exercises/typescript/) Make sure the matching answer under exercises/answers/<lang>/<pattern>/ still passes How to verify pnpm test # runs all exercise + component tests pnpm test:exercises # TypeScript exercises only (faster) Why this is a good first issue Builds on existing structure, scoped to one pattern, teaches the test layout without needing to understand the whole project. See CONTRIBUTING → Good First Contributions.