Skip to main content

PR Requirements

There is a PR template, LLM can generate these based off session work and PR diffs but they're usually full of churn.

Common PR Types (Conventional Commits)

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes only
  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • chore: Changes to the build process, tooling, or libraries
  • perf: A code change that improves performance
  • test: Adding or correcting tests

[1, 2, 3, 4, 5]

eg.

Summary: One or two lines summarising what the PR is doing, don't let scope drift here by saying too much.

Changes: Bullet points of changes (in natural language at a high level, avoid too much code reference unless necessary/niche approach)

Testing: The most important part of the PR. Minimum requirements (if changing/adding any test):

  • Allure report link from a CI/CD (Github Actions) run.

Ideal: Several screenshots proving what you did works along the way, besides just proof of green tests.

Good vs. bad examples​

Good — clear scope, before/after, scoped diff. Worth copying the style of:

  • octostar-frontend#1068 — a model small fix (disable the Save button while a save is in flight): +5/−2 in one file, a one-line SUMMARY, BEFORE/AFTER screen recordings, and a "how this was tested" checklist including a two-browser case. Paired with e2e coverage in tests/front/test_monaco_editor.py (test_save_button_disabled_when_warning_visible + the clean→dirty→saved transition), landed via test PRs #260 / #288.
  • octostar-frontend#801 — states the before/after accessible name, scopes phase 1 vs follow-up explicitly.
  • octostar-frontend#1023 — says exactly what attributes were added and that there's no visual change.
  • octostar-frontend#832 — includes the failing test output and the root cause.

Bad — the reviewer (and a reader six months later) can't tell what changed or why:

  • Vague title, kitchen-sink scope: "More things", "fix: various things", "get-to-green".
  • Large AI-generated diff with no high-level explanation: octostar-frontend#940 — +2,349 lines across 23 files, but the SUMMARY is just a Loom link with the template's "describe the change" placeholder left unfilled. To review it you have to watch a video and read the entire diff.

Size isn't the problem — unexplained size is. Large PRs are fine when they carry a real high-level summary (e.g. frontend #984, ~12k lines, is reviewable because it explains the cascade/token/component structure up front). A short PR with no explanation is just as bad as a huge one; the rule is "explain what and why at a high level," not "keep it small."