Skip to content

Show contribution tracks at the top of CONTRIBUTING.md - #227

Merged
n3wth merged 3 commits into
google:mainfrom
atrearyanuf:docs/contributing-which-track
Oct 30, 2026
Merged

n3wth merged 3 commits into
google:mainfrom
atrearyanuf:docs/contributing-which-track

Conversation

@atrearyanuf

Copy link
Copy Markdown
Contributor

Contribution Type

Please select the track that matches this pull request:

  • Bug Fix / Minor Patch (Targeted fix, non-test diff <= 100 lines and < 3 core files in skills/ or agents/; no design doc required)
  • Feature / Architectural Change -- Stage 1: Design Doc PR (Refs #___ with design-ready | Adds docs/designs/<name>.md and updates docs/designs/README.md; use Refs instead of Closes so the issue stays open for Stage 2)
  • Feature / Architectural Change -- Stage 2: Implementation PR (Closes #___ with pr-ready | Implements merged docs/designs/<name>.md)

Summary of Key Changes

List all key changes made in this pull request and why:

Closes #221.

  • CONTRIBUTING.md: new "Which track is my change?" section before "Design Principles". It links the Contribution Tracks & Workflow section (#contribution-tracks--workflow), the PR template, the feature proposal form, and docs/designs/README.md. It routes by size (a small fix within the Track 1 limits, or anything larger, a new feature, or an architectural change) and does not restate thresholds or steps, so it cannot contradict the track sections.
  • tests/unit/test_link_integrity.py: one hyphen per space in heading slugs. GitHub turns "Contribution Tracks & Workflow" into #contribution-tracks--workflow. The old slug collapsed the two spaces into one hyphen (contribution-tracks-workflow), so the correct link failed test_relative_markdown_links_resolve_on_disk. The slug now replaces each space separately, and test_heading_slug_keeps_one_hyphen_per_space covers this case.
  • Left out: the line "empty or off-topic issues and PRs are closed". Per the review on docs(contributing): show contribution tracks at the top of CONTRIBUTING.md #223, no written policy backs it. I can add it if you point me to where that policy should live.

#223 covers the same issue. This version also links docs/designs/README.md, keeps rule text only in the track sections, and includes the link-test fix that #223's anchor needs. If you'd rather merge #223, the test change here can go in on its own.

Not changed here: the link checker still differs from GitHub for headings with inline code, links, duplicate names, or closing # markers, and it does not check #fragments on links to other files. Those predate this PR.

Human Accountability Affirmation

  • I am a human contributor. I have personally reviewed, understood, and can explain every line of this change in review (using AI tools to write code is welcome, but human understanding of the submitted change is required).

Verification

  • For Design Doc PRs (Stage 1): Executed /egm-review docs/designs/<name>.md, resolved findings via /egm-resolve, and verified relative links (pytest tests/unit/test_link_integrity.py).
  • For Bug Fix / Implementation PRs (Stage 2): Unit tests or test_scenarios.yaml added/updated and pytest tests/unit executed.
  • For Harness Support PRs: Verified plugin installation and end-to-end execution of /egm-brainstorm, /egm-draft, and /egm-review on the target harness; attached execution summary or transcript.

pytest tests/unit: 138 passed, 1 failed. The failure is test_published_claude_runtime_is_current, which already fails on main; open PR #209 fixes it.

Add a "Which track is my change?" section before Design Principles. It
points to the track rules, the PR template, the feature proposal form,
and docs/designs/README.md without restating the rules.

Turn each space in a heading into its own hyphen in the link check, as
GitHub does, so "Contribution Tracks & Workflow" resolves to
#contribution-tracks--workflow. Add a unit test for this slug.

Closes google#221
n3wth
n3wth previously approved these changes Oct 29, 2026

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 4b08bbd. The new section routes to the Track 1 and Track 2 rules without restating them, and the bullets agree with the sections below: the first carries the Track 1 limits, the second sends larger changes to the feature proposal issue and the Track 2 steps. The #contribution-tracks--workflow anchor, the PR template and docs/designs/README.md all resolve.

The slug fix is correct. GitHub keeps one hyphen per space, so "Tracks & Workflow" becomes tracks--workflow. I checked #223's head with the old slug and test_relative_markdown_links_resolve_on_disk fails on this same anchor, so the test change is needed whichever of the two lands first.

One non-blocking test suggestion inline.

I ran tests/unit locally at this head. The one failure is test_published_claude_runtime_is_current, the README.md drift that #209 fixes (still open). The Tests workflow has not run on this head; cla/google and the scope/template check pass.

Nothing blocking.

Comment thread tests/unit/test_link_integrity.py Outdated
Co-authored-by: n3wth <5912894+n3wth@users.noreply.github.com>

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed at 4e04bb4. The only change since 4b08bbd is the test update I suggested: test_heading_slug_keeps_one_hyphen_per_space now also asserts that a plain heading (Design Principles) keeps a single hyphen, so the test guards both cases. The CONTRIBUTING.md section is unchanged from what I reviewed. It still routes to the Track 1 and Track 2 rules without restating them, and the #contribution-tracks--workflow anchor, the PR template and docs/designs/README.md resolve.

I ran tests/unit locally at this head. The one failure is test_published_claude_runtime_is_current, the README.md drift that #209 fixes (still open). The Tests workflow is waiting for workflow approval on this head, so there is no CI result yet; cla/google and the scope/template check pass.

No remaining finding.

@atrearyanuf atrearyanuf changed the title Show contribution tracks at the top of CONTRIBUTING.md Show contribution tracks at the top of CONTRIBUTING.md Oct 29, 2026
@n3wth
n3wth merged commit 3ee1454 into google:main Oct 30, 2026
10 checks passed
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.

Show contribution tracks at the top of CONTRIBUTING.md

2 participants