Handbook contents

Field guide · 7~4 min

Review & merge

Respond in the existing PR, merge when review and checks agree, then bring your local checkout up to date.

What a good review is deciding

Automated checks run first and catch many implementation problems. Human review is where the team decides whether the design is the right one.

  • Architecture: does each model have one clear job, and is useful logic placed where other models in the repo can reuse it?
  • Clinical correctness: are definitions, populations, exclusions and code lists sound?
  • Maintenance: can someone understand the code and see what a future source or definition change would require?

The standard worth holding each other to is the one Google wrote down for its own reviews: approve once the change definitely improves the codebase, even though it is not perfect — there is no perfect model, only a better one. A change that makes things better should not wait days for polish; mark optional suggestions as such (a “nit:” prefix works) so the author can tell what blocks the merge from what is merely worth considering.

Respond to review

# make the requested change, then
git add -u
git commit -m "fix: address review feedback"
git push

Reply in the review thread with what changed. If you disagree, explain the data or design reason there; a review comment is a discussion, not an instruction that must be accepted silently.

Merge and sync

Merge once approvals are present and every required check is green. The project uses squash merge, so the branch lands on main as one tidy commit.

git switch main
git pull
git branch -d feat/short-description

After the merge

Merge is the moment responsibility transfers from you to the pipeline. The deploy workflow builds your changed models into production; from that night on, the scheduled build rebuilds them and runs their tests without you; and your YAML descriptions go live on the docs site and as Snowflake comments. Nothing further is owed unless something fails — which is why the deployment result is worth one look before you move on.

If production fails, keep the PR link and failing job together when asking for help. The useful question is not only “what failed?” but “did this also fail in the PR environment, or is production different?”