PR workflow
How a contribution gets from your fork into main. Read this once;
afterward each PR should take you about ten minutes of process
overhead on top of the actual work.
Branch model
main: the active development branch. All PRs land here.- Artifact branches: per-paper reproducibility branches, named
after the venue (e.g.,
ispass26-artifact). Don't open PRs against these. They are frozen at the artifact submission state. - Your work: a feature branch off
main, named descriptively (add-deepseek-v3,fix-evict-accumulation,docs-cluster-config). Don't push tomaindirectly even if you have permissions.
git checkout main
git pull
git checkout -b add-deepseek-v3
Commit hygiene
- Short imperative one-liner. Same style as the existing log:
Fix incorrect evict_size accumulation,Add Qwen3 model support,Document MoE expert routing. - One logical change per commit. A refactor and a feature in the same commit is a reviewer's nightmare.
- Commit adopted changes only. Record verified bug fixes separately. Do not commit intermediate work: development notes, intermediate measurements or generated results, experimental code, or temporary diagnostic and fix-verification scripts and tests. Validation is still required; its temporary tools and outputs stay local. Exclusion does not authorize deletion.
- Every commit includes documentation updates, even a docs-only commit: the root README.md and affected directory READMEs, AGENTS.md, CHANGELOG.md, and relevant public pages under docs/. Review repository READMEs, including per-directory files, for affected or stale descriptions. Keep README changes concise and regenerate the site's changelog from CHANGELOG.md.
- Audit CLI documentation before release. Compare registered flags, negative forms, defaults and subcommand restrictions with each README index and full reference. Check wrapper forwarding without launching engines; distinguish parser defaults from values resolved by the target engine.
- Document supported behavior, not development sessions. Keep investigation diaries, intermediate experiment notes and session checkpoints out of tracked documentation, including contributor pages. Describe final supported behavior, usage, verified changes and known limitations.
- Inspect the staged diff before every commit. Check both the excluded material and the required documentation surfaces. Never stage an entire dirty worktree without reviewing its contents.
- No AI-tool references or AI attribution trailers in commit messages.
- Don't amend published commits. If you pushed it, follow up with a new commit. Force-pushing your branch is fine before review starts, generally not after.
- There are no pre-commit hooks in this repo, so nothing runs
automatically on commit and
--no-verifyhas nothing to bypass. The checks below are yours to run. - No
Co-authored-byunless someone really did pair-program with you on this commit.
A good commit message:
Fix evict_size accumulation when prefix cache spills to CPU
Spilling counted the block twice: once in the NPU eviction and
again when the second-tier pool inserted it. Drop the second
increment; the test in single_node_memory_instance.json now
matches the bench reference.
A bad one:
fixes
Changelog entries
Edit the root CHANGELOG.md; the website page is generated from it.
- Add pending changes under
Unreleased. Use each applicable heading once:Added,Changed,Deprecated,Removed,Fixed, orSecurity. - Write one or two sentences per user-visible change. Merge related entries into the final behavior rather than appending a new account of every commit.
- Cross-check commits and the net code diff since the previous release, including changed submodules. Existing notes may omit changes; reverted experiments must not be presented as current features.
- Preserve removed options, their replacements, required data refreshes and validation limits. Keep issue/PR links and contributor credit with the change.
- Link to the relevant guide for algorithms, examples and implementation details. Do not publish investigation timelines or intermediate benchmark results.
- Leave published release records intact when consolidating pending changes.
Do not turn
Unreleasedinto a numbered release until that release is approved.
Run pnpm sync-changelog from docs/ to update the tracked page, then
pnpm build to check links and rendered content before publishing.
Before you push
Run through the checklist:
- Smoke run passes. See Validating your changes, step 1.
- Targeted scenarios pass for whatever you touched. Step 2.
- Bench validation hasn't regressed if your change affects end-to-end accuracy. Step 3.
- Conventions checklist:
getattrfallbacks,head_dimhandling, English-only, layer names, noastra-sim/inputs/edits. See Coding conventions. - Documentation accompanies every commit. Check the root and affected directory READMEs, AGENTS.md, CHANGELOG.md, the generated changelog page, and relevant public docs against the commit-hygiene policy above.
- No machine-specific paths or intermediate artifacts in the staged diff,
including temporary verification scripts and tests. The generated site
changelog is an intentional tracked document, not an experiment output.
Sanity-check with
git diff --cached --statandgit diff --cached --check.
Publishing submodule changes
The frontend, ASTRA-Sim and Chakra are separate Git repositories. A parent commit records a submodule commit ID; pushing the parent does not publish that commit to the submodule's remote.
- Check each repository's configured remote, branch and unpublished diff. Keep temporary verification files and private run records out of every commit being published, not only the final working tree.
- Publish required Chakra commits to the configured fork first, then publish ASTRA-Sim with its recorded Chakra pointer. Verify both commits are reachable from their intended remote branches.
- Publish the frontend branch with
git push --recurse-submodules=check. This refuses a parent push when referenced submodule commits are not available on a remote. Do not use--allor--mirrorto include local backup refs.
Use normal fast-forward pushes; if a remote branch has advanced independently, reconcile it before publishing rather than force-pushing over other work. Only submodules with new required commits need a push.
Consumers updating an existing clone should run:
git pull --ff-only
git submodule sync --recursive
git submodule update --init --recursive
./scripts/compile.sh
Run the build inside the documented simulator environment. It rebuilds ASTRA-Sim and installs the pinned Chakra converter; source edits alone do not update an already-installed converter or backend binary.
Opening the PR
Push to your fork (or branch if you have direct access):
git push -u origin add-deepseek-v3
Then open the PR against casys-kaist/LLMServingSim:main. The
description should include:
## What this changes
A 1-3 sentence summary of the user-visible change.
## Why
The motivation: the bug it fixes, the feature it enables, the
research question it lets you ask.
## Validation
The exact command(s) you ran and the key result. For example:
./bench/examples/validate.sh RTXPRO6000/Llama-3.1-8B
-> report all 15 signed Diff% values from summary.txt and their changes
## Notes
Anything subtle: known limitations, related issues, follow-ups
you intentionally did not include.
You don't need a heavy template. The validation section is the one non-negotiable part: it gives the reviewer something concrete to rerun and gives the git log a record of what was checked.
What review looks like
- Initial response: usually within 2-3 days for the first round. Time-zone overlap with KAIST (UTC+9) helps but isn't required.
- Reviewers: at least one of the main contributors (@JaehongCho, @hmchoi) plus whoever owns the touched area. For docs-only PRs, one approval is enough.
- What gets blocked vs. nit-picked:
- Blockers: an unexplained
./serving/validate.shdifference, bench regressions beyond ~5%, convention violations from the "never do this" list, missing docs for new flags. - Nits: naming, code style preferences, doc phrasing. The reviewer will say "nit:" or use the GitHub label. Address them if you agree; defer with a sentence if you don't.
- Blockers: an unexplained
- Conversation style: terse and direct. "This won't work for MoE" is not a personal attack; it's faster than the polite version. Reply in kind.
Squash, rebase, or merge?
The project squashes most PRs to a single commit on main, with
the PR title becoming the commit message. Every constituent commit
must still follow the policy above: squashing does not excuse intermediate
artifacts or missing documentation. If your PR is genuinely best as
multiple commits (e.g., a refactor + a feature
that depends on it), say so in the description and a maintainer
will rebase rather than squash.
Attribution
External contributors get credit in two places:
- GitHub commit history: your authorship is preserved on merge.
CONTRIBUTORS.md: the maintainer adds a line with your GitHub handle and a link to the PR or issue — under "Code" for a merged patch, under "Reports and analysis" for an issue that pinned down a real problem. Reports get their own section rather than a footnote, and the changelog entry for the fix names you too.
You don't need to add yourself to the contributors list in your PR. The maintainer adds it on merge.
After merge
- Pull
mainbefore starting the next change. Your local branch is no longer authoritative. - Delete the merged branch locally and on the remote
(GitHub offers a button after merge;
git branch -d add-deepseek-v3locally). - Re-run your scenarios against
mainafter the merge. There is no test CI to watch: the only workflow isdeploy-docs.yml, which builds the docs site and says nothing about the simulator. If something broke that the review missed, the way you find out is by running./serving/validate.shonmain. - My PR sat for a week with no reviews. Ping the PR with a one-liner. Maintainers do miss notifications.
- A reviewer requested changes I disagree with. Explain your reasoning in a comment. If you still disagree after the reviewer's reply, escalate by tagging the other main contributor for a tiebreaker. We'd rather have the discussion than land the wrong design.
- My change regressed bench beyond what I expected. Don't merge it. Open the PR as a draft and tag the regression in the description; we'll figure out together whether it's a bug in your change, in the existing baseline, or in the validation methodology.
- I broke something on
main. It happens. Open a follow-up PR with aFix ...commit; don'tgit push --forcetomain.
What's next
You've got the full picture now. Go pick a starter issue or open
a new one with [contributor] in the title to discuss what you'd
like to work on.
Welcome aboard.