docs(framework): simplify contribution to one issue-first path - #562
Merged
Conversation
Replace the role-differentiated entry table with a single flow: any contributor opens a Rapide or Détaillée issue, a Certifié or Habilité validates it (board Status Ideation -> Todo), then anyone opens the PR. Drops the Certifié-only PR gate and the 7-day roadmap vote for these issues; adds a Principles section (anti-slop, token economy, skill structure, memory upkeep). Closes phase-1 of aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md
CONTRIBUTING.md: translate the how-to-contribute and Principles sections to English (repo convention), compress to a plain 1-2-3-4 list up top, drop the sub-numbering that clashed with it, and trim Releases to a pointer (detail already lives in RELEASE.md/MAINTAINERS.md). GOVERNANCE.md: finish the Habilite/Certifie -> Trusted Partner/ Certified Member rename started earlier, and fix the team links, which pointed at stale slugs (habilitated/certified instead of the real trusted-partners/certified-members). Propagate the same rename to CONTRIBUTORS.md and docs/MAINTAINERS.md to remove the duplication/drift risk. Trim ROADMAP.md's "How to influence" section and add the missing Thursday 10:30 Discord sync.
CONTRIBUTORS.md wasn't a GitHub-special file and was linked from nowhere but MAINTAINERS.md; its only real content (the contrib.rocks mosaic) now lives in README.md's existing Contributing section. Rights language (merge, veto, review, CODEOWNERS) now says Maintainer throughout instead of Trusted Partner, matching the roles ladder's own top rung: Trusted Partner and AIDD Staff are the two paths into one Maintainer tier, not two different rights holders. Trusted Partner is kept only as the promotion-path name. Also fixes CODEOWNERS, which still pointed at the stale @ai-driven-dev/habilitated team/comment - real merge-review assignment would have silently broken.
Issue templates and their CONTRIBUTING.md links were half-English half-French (Contribution Rapide/Detaillee) - now Quick/Detailed Contribution throughout. Fixes two breaks from the terminology rename: CONTRIBUTING.md linked to GOVERNANCE.md#-code-decisions-merging, a heading that no longer exists after the section was retitled; GOVERNANCE.md's Maintainer row listed the same team link twice in the Team column.
Branch-off-next was said three times (mermaid, step 3, PR section); "no one merges their own PR" restated what GOVERNANCE.md#-code-decisions already covers. Kept one mention of each.
Dropped the Releases section (pure restatement of the Commit bullet's RELEASE.md link), the hotfix/* edge case, the label-automation and squash-merge trivia, and two Reference bullets aimed at plugin authors rather than a first-time contributor. Every remaining line is one clause, no nested asides.
Step 1 (open an issue) now reads as its own stopping point - reporting or proposing doesn't commit you to building it, and step 3 says anyone can pick up a validated issue, not just its opener. Moved Principles right after the flow (was buried after Set up), and added back "Claude Code syntax only" - present in the file before this branch's rewrite, dropped by accident. Set up and Make your change were cut too hard: restored what `make setup` actually does and the reload/session-restart + one-scope- per-commit facts. Open a pull request now links the PR template directly, it only named it before.
…ool test Points back to Principles, and testing now says what "locally" means concretely: Claude plus at least one other tool, since the CLI's Claude-to-per-tool translation is the part most likely to break.
Bug Report is the same mechanism as Quick/Detailed Contribution - one issue template, same board, same validation gate. Listing it as a separate "Reporting a bug" section duplicated the concept; it's now a third choice in step 1, mermaid updated to match. The Discussions caveat moved up alongside it since that section is gone.
Bug/Quick/Detailed now render as three parallel entries converging on validation, then the linear dev tail: Set up, Changes, PR, Review, Merged - matching the section order below instead of restating branch/commit patterns already linked there. Principles gets one line of framing before the bullets.
Step 1 crammed three template links plus a stop-here note plus a Discussions redirect into one line. Discussions now gets its own sentence before the mermaid; step 1 just lists the three templates.
The question/exchange vs bug/improvement/feature split was only in prose above the diagram. Added a Start node that branches to Discussions or the three issue templates, so the diagram carries the fork instead of the sentence above it.
Both nodes just said their name with no hint of what separates them. Added the field difference (problem+solution vs scope+acceptance criteria) that actually distinguishes the two templates. Also fixed the source list numbering (two "1." items) now that Discussions is its own bullet.
Dropped the explicit "Report a security vulnerability" contact link - GitHub already auto-adds its own shield-icon tile for that once SECURITY.md + advisories are enabled, ours was a dead ringer. Dropped "Website" too, not an actionable choice at the point someone's about to open an issue.
Only the display name: field changed to Quick/Detailed Contribution - the files themselves stayed feature_request.yml/roadmap.yml, a filename/purpose mismatch for anyone editing them later. Renamed to quick_contribution.yml/detailed_contribution.yml and updated the ?template= links in CONTRIBUTING.md to match. Checked every other in-repo mention first - only two historical plan docs reference the old names, left as records of what existed at the time.
blafourcade
marked this pull request as ready for review
July 31, 2026 03:16
1 task
blafourcade
added a commit
that referenced
this pull request
Jul 31, 2026
….md (#563) These three never made it into #562 - individually staged files got git add'ed by name throughout that branch's work, and these three were never among them, then the branch squash-merged before anyone noticed. - ROADMAP.md: replace the placeholder "Thursdays 10:30" text with the real weekly Discord event link. - RELEASE.md: trim the commit-type -> changelog table and restate, duplicated with aidd_docs/memory/vcs.md and docs/MAINTAINERS.md. - UPGRADE.md: drop the frozen v3->v4 migration guide, no longer needed. No file in the repo linked to it.
blafourcade
added a commit
that referenced
this pull request
Jul 31, 2026
* docs(framework): simplify contribution to one issue-first path Replace the role-differentiated entry table with a single flow: any contributor opens a Rapide or Détaillée issue, a Certifié or Habilité validates it (board Status Ideation -> Todo), then anyone opens the PR. Drops the Certifié-only PR gate and the 7-day roadmap vote for these issues; adds a Principles section (anti-slop, token economy, skill structure, memory upkeep). Closes phase-1 of aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md * docs(framework): mark contribution simplification plan implemented * docs(framework): tighten contribution flow, sync renamed roles CONTRIBUTING.md: translate the how-to-contribute and Principles sections to English (repo convention), compress to a plain 1-2-3-4 list up top, drop the sub-numbering that clashed with it, and trim Releases to a pointer (detail already lives in RELEASE.md/MAINTAINERS.md). GOVERNANCE.md: finish the Habilite/Certifie -> Trusted Partner/ Certified Member rename started earlier, and fix the team links, which pointed at stale slugs (habilitated/certified instead of the real trusted-partners/certified-members). Propagate the same rename to CONTRIBUTORS.md and docs/MAINTAINERS.md to remove the duplication/drift risk. Trim ROADMAP.md's "How to influence" section and add the missing Thursday 10:30 Discord sync. * docs(framework): fold CONTRIBUTORS.md into README, unify on Maintainer CONTRIBUTORS.md wasn't a GitHub-special file and was linked from nowhere but MAINTAINERS.md; its only real content (the contrib.rocks mosaic) now lives in README.md's existing Contributing section. Rights language (merge, veto, review, CODEOWNERS) now says Maintainer throughout instead of Trusted Partner, matching the roles ladder's own top rung: Trusted Partner and AIDD Staff are the two paths into one Maintainer tier, not two different rights holders. Trusted Partner is kept only as the promotion-path name. Also fixes CODEOWNERS, which still pointed at the stale @ai-driven-dev/habilitated team/comment - real merge-review assignment would have silently broken. * docs(framework): translate template names, fix anchors and links Issue templates and their CONTRIBUTING.md links were half-English half-French (Contribution Rapide/Detaillee) - now Quick/Detailed Contribution throughout. Fixes two breaks from the terminology rename: CONTRIBUTING.md linked to GOVERNANCE.md#-code-decisions-merging, a heading that no longer exists after the section was retitled; GOVERNANCE.md's Maintainer row listed the same team link twice in the Team column. * docs(framework): cut repeated branch/merge facts in CONTRIBUTING.md Branch-off-next was said three times (mermaid, step 3, PR section); "no one merges their own PR" restated what GOVERNANCE.md#-code-decisions already covers. Kept one mention of each. * docs(framework): cut CONTRIBUTING.md to what a newcomer needs Dropped the Releases section (pure restatement of the Commit bullet's RELEASE.md link), the hotfix/* edge case, the label-automation and squash-merge trivia, and two Reference bullets aimed at plugin authors rather than a first-time contributor. Every remaining line is one clause, no nested asides. * docs(framework): clarify report-vs-build split, restore cut facts Step 1 (open an issue) now reads as its own stopping point - reporting or proposing doesn't commit you to building it, and step 3 says anyone can pick up a validated issue, not just its opener. Moved Principles right after the flow (was buried after Set up), and added back "Claude Code syntax only" - present in the file before this branch's rewrite, dropped by accident. Set up and Make your change were cut too hard: restored what `make setup` actually does and the reload/session-restart + one-scope- per-commit facts. Open a pull request now links the PR template directly, it only named it before. * docs(framework): flesh out Make your change with principles + multi-tool test Points back to Principles, and testing now says what "locally" means concretely: Claude plus at least one other tool, since the CLI's Claude-to-per-tool translation is the part most likely to break. * docs(framework): fold bug reports into the template list Bug Report is the same mechanism as Quick/Detailed Contribution - one issue template, same board, same validation gate. Listing it as a separate "Reporting a bug" section duplicated the concept; it's now a third choice in step 1, mermaid updated to match. The Discussions caveat moved up alongside it since that section is gone. * docs(framework): mermaid shows the 3 template branches, Principles intro Bug/Quick/Detailed now render as three parallel entries converging on validation, then the linear dev tail: Set up, Changes, PR, Review, Merged - matching the section order below instead of restating branch/commit patterns already linked there. Principles gets one line of framing before the bullets. * docs(framework): split Discussions from the issue templates line Step 1 crammed three template links plus a stop-here note plus a Discussions redirect into one line. Discussions now gets its own sentence before the mermaid; step 1 just lists the three templates. * docs(framework): show the discussion-vs-issue fork in the mermaid itself The question/exchange vs bug/improvement/feature split was only in prose above the diagram. Added a Start node that branches to Discussions or the three issue templates, so the diagram carries the fork instead of the sentence above it. * docs(framework): distinguish Quick vs Detailed in the diagram Both nodes just said their name with no hint of what separates them. Added the field difference (problem+solution vs scope+acceptance criteria) that actually distinguishes the two templates. Also fixed the source list numbering (two "1." items) now that Discussions is its own bullet. * docs(framework): trim the issue picker's contact links Dropped the explicit "Report a security vulnerability" contact link - GitHub already auto-adds its own shield-icon tile for that once SECURITY.md + advisories are enabled, ours was a dead ringer. Dropped "Website" too, not an actionable choice at the point someone's about to open an issue. * docs(framework): actually rename the issue template files Only the display name: field changed to Quick/Detailed Contribution - the files themselves stayed feature_request.yml/roadmap.yml, a filename/purpose mismatch for anyone editing them later. Renamed to quick_contribution.yml/detailed_contribution.yml and updated the ?template= links in CONTRIBUTING.md to match. Checked every other in-repo mention first - only two historical plan docs reference the old names, left as records of what existed at the time.
blafourcade
added a commit
that referenced
this pull request
Jul 31, 2026
….md (#563) These three never made it into #562 - individually staged files got git add'ed by name throughout that branch's work, and these three were never among them, then the branch squash-merged before anyone noticed. - ROADMAP.md: replace the placeholder "Thursdays 10:30" text with the real weekly Discord event link. - RELEASE.md: trim the commit-type -> changelog table and restate, duplicated with aidd_docs/memory/vcs.md and docs/MAINTAINERS.md. - UPGRADE.md: drop the frozen v3->v4 migration guide, no longer needed. No file in the repo linked to it.
blafourcade
added a commit
that referenced
this pull request
Jul 31, 2026
* docs(framework): simplify contribution to one issue-first path Replace the role-differentiated entry table with a single flow: any contributor opens a Rapide or Détaillée issue, a Certifié or Habilité validates it (board Status Ideation -> Todo), then anyone opens the PR. Drops the Certifié-only PR gate and the 7-day roadmap vote for these issues; adds a Principles section (anti-slop, token economy, skill structure, memory upkeep). Closes phase-1 of aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md * docs(framework): mark contribution simplification plan implemented * docs(framework): tighten contribution flow, sync renamed roles CONTRIBUTING.md: translate the how-to-contribute and Principles sections to English (repo convention), compress to a plain 1-2-3-4 list up top, drop the sub-numbering that clashed with it, and trim Releases to a pointer (detail already lives in RELEASE.md/MAINTAINERS.md). GOVERNANCE.md: finish the Habilite/Certifie -> Trusted Partner/ Certified Member rename started earlier, and fix the team links, which pointed at stale slugs (habilitated/certified instead of the real trusted-partners/certified-members). Propagate the same rename to CONTRIBUTORS.md and docs/MAINTAINERS.md to remove the duplication/drift risk. Trim ROADMAP.md's "How to influence" section and add the missing Thursday 10:30 Discord sync. * docs(framework): fold CONTRIBUTORS.md into README, unify on Maintainer CONTRIBUTORS.md wasn't a GitHub-special file and was linked from nowhere but MAINTAINERS.md; its only real content (the contrib.rocks mosaic) now lives in README.md's existing Contributing section. Rights language (merge, veto, review, CODEOWNERS) now says Maintainer throughout instead of Trusted Partner, matching the roles ladder's own top rung: Trusted Partner and AIDD Staff are the two paths into one Maintainer tier, not two different rights holders. Trusted Partner is kept only as the promotion-path name. Also fixes CODEOWNERS, which still pointed at the stale @ai-driven-dev/habilitated team/comment - real merge-review assignment would have silently broken. * docs(framework): translate template names, fix anchors and links Issue templates and their CONTRIBUTING.md links were half-English half-French (Contribution Rapide/Detaillee) - now Quick/Detailed Contribution throughout. Fixes two breaks from the terminology rename: CONTRIBUTING.md linked to GOVERNANCE.md#-code-decisions-merging, a heading that no longer exists after the section was retitled; GOVERNANCE.md's Maintainer row listed the same team link twice in the Team column. * docs(framework): cut repeated branch/merge facts in CONTRIBUTING.md Branch-off-next was said three times (mermaid, step 3, PR section); "no one merges their own PR" restated what GOVERNANCE.md#-code-decisions already covers. Kept one mention of each. * docs(framework): cut CONTRIBUTING.md to what a newcomer needs Dropped the Releases section (pure restatement of the Commit bullet's RELEASE.md link), the hotfix/* edge case, the label-automation and squash-merge trivia, and two Reference bullets aimed at plugin authors rather than a first-time contributor. Every remaining line is one clause, no nested asides. * docs(framework): clarify report-vs-build split, restore cut facts Step 1 (open an issue) now reads as its own stopping point - reporting or proposing doesn't commit you to building it, and step 3 says anyone can pick up a validated issue, not just its opener. Moved Principles right after the flow (was buried after Set up), and added back "Claude Code syntax only" - present in the file before this branch's rewrite, dropped by accident. Set up and Make your change were cut too hard: restored what `make setup` actually does and the reload/session-restart + one-scope- per-commit facts. Open a pull request now links the PR template directly, it only named it before. * docs(framework): flesh out Make your change with principles + multi-tool test Points back to Principles, and testing now says what "locally" means concretely: Claude plus at least one other tool, since the CLI's Claude-to-per-tool translation is the part most likely to break. * docs(framework): fold bug reports into the template list Bug Report is the same mechanism as Quick/Detailed Contribution - one issue template, same board, same validation gate. Listing it as a separate "Reporting a bug" section duplicated the concept; it's now a third choice in step 1, mermaid updated to match. The Discussions caveat moved up alongside it since that section is gone. * docs(framework): mermaid shows the 3 template branches, Principles intro Bug/Quick/Detailed now render as three parallel entries converging on validation, then the linear dev tail: Set up, Changes, PR, Review, Merged - matching the section order below instead of restating branch/commit patterns already linked there. Principles gets one line of framing before the bullets. * docs(framework): split Discussions from the issue templates line Step 1 crammed three template links plus a stop-here note plus a Discussions redirect into one line. Discussions now gets its own sentence before the mermaid; step 1 just lists the three templates. * docs(framework): show the discussion-vs-issue fork in the mermaid itself The question/exchange vs bug/improvement/feature split was only in prose above the diagram. Added a Start node that branches to Discussions or the three issue templates, so the diagram carries the fork instead of the sentence above it. * docs(framework): distinguish Quick vs Detailed in the diagram Both nodes just said their name with no hint of what separates them. Added the field difference (problem+solution vs scope+acceptance criteria) that actually distinguishes the two templates. Also fixed the source list numbering (two "1." items) now that Discussions is its own bullet. * docs(framework): trim the issue picker's contact links Dropped the explicit "Report a security vulnerability" contact link - GitHub already auto-adds its own shield-icon tile for that once SECURITY.md + advisories are enabled, ours was a dead ringer. Dropped "Website" too, not an actionable choice at the point someone's about to open an issue. * docs(framework): actually rename the issue template files Only the display name: field changed to Quick/Detailed Contribution - the files themselves stayed feature_request.yml/roadmap.yml, a filename/purpose mismatch for anyone editing them later. Renamed to quick_contribution.yml/detailed_contribution.yml and updated the ?template= links in CONTRIBUTING.md to match. Checked every other in-repo mention first - only two historical plan docs reference the old names, left as records of what existed at the time.
blafourcade
added a commit
that referenced
this pull request
Jul 31, 2026
….md (#563) These three never made it into #562 - individually staged files got git add'ed by name throughout that branch's work, and these three were never among them, then the branch squash-merged before anyone noticed. - ROADMAP.md: replace the placeholder "Thursdays 10:30" text with the real weekly Discord event link. - RELEASE.md: trim the commit-type -> changelog table and restate, duplicated with aidd_docs/memory/vcs.md and docs/MAINTAINERS.md. - UPGRADE.md: drop the frozen v3->v4 migration guide, no longer needed. No file in the repo linked to it.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 What & why
Replaces the role-gated contribution model with one path: open an issue (Bug, Quick, or Detailed), get it validated, then anyone can open the PR. Drops the Certifié-only PR gate and the 7-day roadmap vote for these issues.
🛠️ How it works
CONTRIBUTING.mdrewritten around the issue-first flow: a mermaid diagram (Discussions/Bug/Quick/Detailed → validate → set up → PR → review → merge) and a Principles section (no slop, token economy, Claude-syntax-only, skill structure, memory upkeep).GOVERNANCE.md: dropped Certifié's PR-opening right; rights language now says Maintainer (the umbrella for Trusted Partner + AIDD Staff) instead of narrowly Trusted Partner; fixed stale team links (certified/habilitated→ the realcertified-members/trusted-partners)..github/CODEOWNERS: fixed a broken team reference — pointed at@ai-driven-dev/habilitated, which doesn't exist.feature_request.yml→ Quick Contribution,roadmap.yml→ Detailed Contribution, both reframed as open to anyone instead of role/vote-gated..github/ISSUE_TEMPLATE/config.yml: dropped a duplicate security contact link (GitHub auto-adds one) and the non-actionable Website link.CONTRIBUTORS.mddeleted; its mosaic folded into README's Contributing section — wasn't a GitHub-special file and was linked from nowhere butdocs/MAINTAINERS.md.ROADMAP.mdtrimmed restated vote mechanics, added the weekly Discord sync.docs/MAINTAINERS.mdsynced to the same terminology.Todo— the validation gate this flow depends on didn't actually exist until this was changed.🧪 How to verify
CONTRIBUTING.mdtop to bottom as a first-time contributor.make check— pre-commit (markdown links, commitlint) green on every commit.Ideation-default fix lives in the GitHub Project's own workflow config, not in this repo — not version-controlled, can't be verified from this diff alone.@ai-driven-dev/trusted-partnersactually has the members GOVERNANCE.md/CODEOWNERS now assume.🔗 Linked issue
(none)
✅ I certify