Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
71 lines (48 loc) · 3.13 KB

CONTRIBUTING.md

File metadata and controls

71 lines (48 loc) · 3.13 KB
Raw

Contributing

This project favors small, reviewable changes and fast feedback. Reliability rules should protect the main learning flow without turning minor edits into a release ceremony.

Development workflow

  1. Start from an up-to-date main branch.
  2. Create a short-lived branch such as feature/clarification-flow, fix/url-timeout, or docs/review-policy.
  3. Keep the diff focused on one user-visible outcome.
  4. Run npm run ci before opening a pull request.
  5. Complete the pull request template, including risk and rollback notes.
  6. Merge only after required checks pass and review comments are resolved.

Do not push feature work directly to main. Do not force-push shared branches.

Risk levels

Risk Typical changes Required review
Low Copy, documentation, isolated styles Passing CI and recorded self-review; a second reviewer is optional
Medium User interaction, API response, shared behavior Passing CI and one substantive review when another maintainer is available
High URL fetching, security boundaries, deployment, compatibility Passing CI and approval from a maintainer other than the author

A review is substantive when it checks behavior, failure modes, scope, tests, and rollback. An approval without reading the diff does not satisfy this policy.

For a single-maintainer repository, GitHub cannot provide an independent approval. Use the PR checklist, review the final diff after a short context break, and require CI. Add mandatory independent approval once a second maintainer is active; do not configure a branch rule that makes emergency maintenance impossible before then.

Verification

Run the same command used by GitHub Actions:

npm run ci

It performs JavaScript syntax checks and starts a real local server for smoke tests covering:

  • the compact window entry page;
  • precise term analysis;
  • ambiguous-term clarification;
  • clarified summaries;
  • follow-up usage and examples;
  • private-network URL protection.

UI changes also require a manual desktop check. Changes to the mobile breakpoint require a mobile viewport check. Add a regression test whenever a bug can be expressed reliably at the API or DOM level.

Definition of done

A change is ready to merge when:

  • its user-visible outcome is described;
  • the diff contains no unrelated cleanup;
  • loading, empty, error, and recovery states were considered;
  • behavior changes have focused tests;
  • npm run ci passes;
  • the rollback plan is clear;
  • review comments are resolved.

Releases and rollback

Use semantic versions:

  • patch: fixes with no intended contract change;
  • minor: backward-compatible features;
  • major: incompatible behavior or API changes.

Update CHANGELOG.md, merge the release PR, and create a matching vX.Y.Z tag. The default rollback is a GitHub revert PR. If a change alters stored data or an external contract, document the additional rollback steps before merge.

Emergency fixes

An urgent production fix may use a shortened PR, but it still requires the smoke check and a written rollback plan. Complete any skipped review or regression test immediately after service is restored.