# Contributing to ARIS-in-AI-Offer

[English](CONTRIBUTING.md) | [中文版](CONTRIBUTING_CN.md)

Thanks for stopping by 🌱 — this repo exists so that 2026 AI campus recruiting (秋招) is a bit less painful, and so future cohorts have a base to build on. One person can only cover so much; PRs and issues are equally welcome.

## Ways to contribute

- **Add a new cheat sheet** on a topic the current collection doesn't cover (e.g. Diffusion Post-Training, Flow-DPO/OPD, Audio Gen, LLM-as-Judge, Long-Video Diffusion, …).
- **Update an existing cheat sheet** when new frontier work breaks an old claim (e.g. new SOTA on SWE-bench, a new MCP spec revision).
- **Fix a math / code / citation bug** — every tutorial has a cross-model `codex GPT-5.5 xhigh` audit trail in `*.review.json`, but reviewers miss things too.
- **Improve rendering / styling** — `tools/render_html.py` and `tools/templates/` live in this repo; PR rendering improvements there.
- **Translate** — add an English version of a tutorial body (currently most tutorials are Chinese with English technical terms inline).

## How to add a new cheat sheet — the ARIS workflow

Every tutorial in this repo was generated by ARIS's `/interview-cheatsheet` + `/render-html` skills. To stay consistent, **please use the same workflow** when you contribute:

1. **Install ARIS** (skill source is bundled in `skills/`; canonical home is the [ARIS main repo](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep)). With Claude Code: `bash <(curl -s https://raw.githubusercontent.com/wanshuiyin/Auto-claude-code-research-in-sleep/main/tools/install_aris.sh)`
2. **Invoke** `/interview-cheatsheet "<TOPIC>"` from inside this repo. The skill auto-runs the cross-model codex review gate + render-html.
3. **Review** the generated `.md` / `.html` / `.review.json` files yourself before pushing.
4. **Open a PR** with all three files (MD source, HTML render, review JSON) plus a row added to README.md / README_CN.md in the right category.

If you want to do it by hand without ARIS, that's fine too — just match the structure of an existing tutorial (e.g. `docs/tutorials/attention_tutorial.md`) and run `tools/render_html.py` to render.

## Style guide (strict)

These rules came from review-loop lessons learned across the first 16 tutorials:

| Rule | Why | How |
|---|---|---|
| Heading: `## §N Title` (space after §N) | Older `§NTitle` glued | always have a space |
| Math in tables: `\lvert x \rvert` not `\|x\|` | `\|` in markdown table = cell separator | use LaTeX explicit form |
| `<` in math: `\lt`, `>` in math: `\gt` | Raw `<t` gets parsed as HTML start tag, breaks render | escape via `\lt` / `\gt` |
| Callouts (`> 💡 / ⚠️ / ✅ / ❌`) followed by list: **blank line between** | Else renderer ambiguity | enforce blank-line separator |
| Sections: §0 TL;DR · §1 directly-grokable intuition · §2-§9 math+code+variants · §10 25-Q&A (L1 必会 × 10 / L2 进阶 × 10 / L3 顶级 lab × 5) · §A optional appendix | matches ARIS pilot pattern | follow numbered structure |
| No personal info | privacy + general portability | byline goes via `--author` flag at render time; ban: SJTU JHC / Server5 / job market / `/Users/...` / specific lab |

See `skills/render-html/SKILL.md` and `skills/interview-cheatsheet/SKILL.md` for the full contract.

## Pull request process

1. Make sure your changes are well-documented (include the `.review.json` so reviewers can see your audit trail).
2. Update **both** `README.md` and `README_CN.md` if you add a new tutorial — pick the right category bucket (General / Post-Training & Reasoning / LLM Architecture & Systems / Generative Models — Theory & Tokenizers / Generation Systems / Multimodal / Agents).
3. Keep PRs focused on a single topic — one tutorial per PR.
4. Clear commit messages — `docs(tutorials): add <Topic> cheat sheet (rendered via /render-html)` is the convention.

### PR checklist

- [ ] `.md` source follows the style guide above
- [ ] `.html` is freshly rendered via `tools/render_html.py`
- [ ] `.review.json` includes cross-model codex audit trail (math/code review verdict + render review verdict + thread IDs)
- [ ] No personal info beyond the byline
- [ ] Both `README.md` + `README_CN.md` updated
- [ ] Citations are real and verifiable (no hallucinated authors / years / venues)

## Honest disclaimer

The existing tutorials are best-effort but the field moves fast. If you spot:
- a paper credited to the wrong author / year / venue,
- a math derivation that drops a term,
- code that wouldn't actually run,
- a claim about a benchmark / SOTA that's now stale,
- or just unclear writing,

… please open an issue or PR. We'll fix it together. Reviewers (including cross-model codex audits) miss things; community eyes catch them.

## Code of conduct

- Be respectful and constructive — assume good faith.
- Focus feedback on the work, not the person.
- Help others learn; this is a study resource first.

## Questions?

Open an issue, or come find us in the [ARIS main repo](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep) WeChat / Discord (QR + link in that repo's README).

## License

By contributing, you agree your contributions will be licensed under MIT — same as the rest of the repo.
