Skip to content

docs: add rules for every change - #840

Merged
yaythomas merged 1 commit into
mainfrom
docs/contributing-change-rules
Oct 25, 2026
Merged

yaythomas merged 1 commit into
mainfrom
docs/contributing-change-rules

Conversation

@yaythomas

Copy link
Copy Markdown
Contributor

Issue #, if available

None.

Description of changes

This PR copies the rules for every change from JS SDK PR #1094: add rules for every change to CONTRIBUTING and the PR template. The rules keep each change as small as the problem, for people and for coding agents.

  1. CONTRIBUTING.md gets the section "Rules for every change", under "Contributing via Pull Requests". It has the same 9 rules as the JS SDK. Two sentences are left out, because they point to material that only the JS repository has:
    • rule 3: "A change to an SDK invariant needs an ADR in docs/adr instead."
    • rule 5: "A contract test is never edited to make a change pass (see SDK invariants)."
  2. A new .github/pull_request_template.md gives the repository its own template. Until now, GitHub used the aws organization's default template, which asks only for an issue and a description. The new template keeps those two prompts and the default's license sentence. It adds the Design, Assumptions and Decisions sections and the three checklist items from the JS template.
  3. AGENTS.md links to the new section from its "Working in this repository" list.

No code changes.

Design

  • Design note: this description.
  • Simpler options considered:
    • Add only the CONTRIBUTING.md section, without a template. Rejected, because the template is where a contributor writes the design, the assumptions and the decisions.
    • Copy the JS template as it is. Rejected, because it would also change the license sentence and add sections that the JS PR did not add (Demo/Screenshots, Testing).
  • Net change: documentation only. No source lines and no public API members change.

Assumptions

Decisions not covered by the issue or the design note

  • The rule text stays identical to the JS text, apart from the two sentences above. So the two copies are easy to compare.
  • Rule 5 adds nothing about conformance tests. Step 4 of the pull request steps already covers them.
  • .github/prompts/ai-pr-review.md is unchanged. It already tells the AI reviewer to read CONTRIBUTING.md from the base branch. So the reviewer reads the rules once this PR is merged.
  • The JS PR is approved but not merged. If its review changes the rules, a follow-up PR here makes the same change.

Checklist

  • Every new branch has a test that fails without it (rule 4): no code
  • For a bug fix: the first commit adds a test that fails on the current code (rule 5): not a bug fix
  • Every edited test expectation is listed in the description, with the reason (rule 5): none

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Copy the rules for every change from the JS SDK, so both SDKs ask the
same of people and coding agents.

- CONTRIBUTING.md gets the section "Rules for every change" with the
  same 9 rules. Two sentences are left out because they point to
  JS-only material: the ADR folder and the SDK invariants section.
- A new .github/pull_request_template.md replaces the aws
  organization's default template for this repository. It keeps the
  default's prompts and license sentence, and adds the Design,
  Assumptions and Decisions sections and three checklist items from
  the JS template.
- AGENTS.md links to the new section.

Documentation only.
@yaythomas
yaythomas deployed to ai-pr-review-runtime October 25, 2026 20:03 — with GitHub Actions Active
@yaythomas
yaythomas deployed to ai-pr-review-runtime October 25, 2026 20:03 — with GitHub Actions Active
@github-actions

Copy link
Copy Markdown
Contributor

Codex AI review

No actionable findings. The changes affect only contribution guidance and the PR template, with no identified runtime regression risk. Tests were not run, as requested.

Reviewed commit 74e4eb497973e69773f1ddca557c3c0f8062fb36. Workflow run

@yaythomas
yaythomas merged commit e7e1305 into main Oct 25, 2026
27 checks passed
@yaythomas
yaythomas deleted the docs/contributing-change-rules branch October 25, 2026 20:22

This branch was successfully deployed

1 active deployment
ai-pr-review-runtime — 74e4eb49 Deployed Oct 25, 2026 by yaythomas via ai-pr-review / Codex review / Generate Codex review #2411
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants