docs: update Suggesting Features section with Discussion-first process

[lml2468]

Summary

Updates the Suggesting Features section in CONTRIBUTING.md to reflect Octo's new Discussion-first governance model.

Changes

• Replaces the old "use the Feature Request template" one-liner with a clear 4-step process: Discussion → consensus → Issue → Board
• Links to the new GOVERNANCE.md in the community repo for full details
• Keeps the escape hatch: minor/small features may still be filed directly as Issues

Related

• community PR #2 — adds GOVERNANCE.md

[yujiawei]

Code Review — PR #9 (.github)

Summary

Documentation-only change that rewrites the Suggesting Features section in CONTRIBUTING.md to describe a Discussion-first workflow, with a link to the (incoming) GOVERNANCE.md in the community repo. The new content is well-structured: 4 numbered steps, an explicit escape hatch for small features, and a friendly "open a Discussion if unsure" closer. Diff is +13/-4, single file, no executable code.

I verified the cross-repo references:

• The community repo and the Ideas discussion category both exist (https://github.com/Mininglamp-OSS/community/discussions/categories/ideas resolves).
• The Feature Request issue template referenced in the escape-hatch paragraph exists in this repo as ISSUE_TEMPLATE/feature_request.yml.
• The Octo Board link points to the org-level Projects index, which is fine.

The change is consistent with the existing "Issue or Discussion?" section at the top of the file and with the org's stated direction.

Findings

P1 — GOVERNANCE.md link will 404 if this PR merges before community PR #2

CONTRIBUTING.md line ~81 in the new diff:

> See [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full process.

The PR body itself acknowledges that GOVERNANCE.md is added by Mininglamp-OSS/community#2, which is still OPEN. Resolving the URL today returns 404. If this PR lands first, the most prominent link in the new section is broken until the community PR merges.

Suggested action: gate this on community#2, e.g. one of:

1. Merge ordering — merge community#2 first, this PR second. Simplest. Worth noting in the PR description as a checklist item.
2. Pin the ref — temporarily point the link at the open PR's branch (.../community/blob/docs/add-governance/GOVERNANCE.md) and follow up to switch back to main after merge. Slightly ugly but rules out a window of brokenness.
3. Auto-merge with a dependency — set this PR to auto-merge after community#2, if the org uses that flow.

Option 1 is the cleanest. This is the only finding I'd consider blocking, and it's procedural rather than a defect in the diff itself.

P2 — Minor friction with the existing "Issue or Discussion?" section

Top of the file already says (lines 9–17):

Open an Issue when: … You have a concrete feature request — need is clearly defined with a specific use case
Open a Discussion when: … You have an early-stage idea to share → Ideas

The new section adds a stricter rule:

Significant features require a Discussion before an Issue.

A reader could reasonably hold both rules in their head and still wonder which path applies to a "concrete but significant" feature request. The two sections aren't contradictory — "concrete feature request" can be read as "small, well-scoped feature" — but the boundary is implicit.

Suggested action (non-blocking): either

• Add a one-liner in the new section that bridges to the existing rubric, e.g.: "This refines the rule in Issue or Discussion?: even a concrete feature request that is significant in scope should start as a Discussion.", or
• Tighten the top-of-file bullet to something like: "You have a small, concrete feature request …" so the two sections don't appear to give different answers to the same question.

P2 — "Significant" vs. "minor" is undefined

For minor improvements or small self-contained features, you may open an Issue directly …

The line draws a line between "significant" (Discussion required) and "minor / small self-contained" (Issue OK), but doesn't define either. In practice this means contributors have to guess, and maintainers will spend cycles converting Issues to Discussions.

Suggested action (non-blocking): add 2–3 concrete examples or a rough heuristic, e.g. "Roughly: anything that changes a public API, adds a new module, or affects more than one repo is 'significant'. Bug-adjacent improvements, small ergonomic wins, and documentation tweaks are 'minor'." Even one sentence reduces the ambiguity dramatically.

P2 — Step 3 wording is a touch passive

3. **A maintainer converts it.** Once consensus is reached, a maintainer closes the Discussion and creates a tracking Issue …

"Closes the Discussion" is a hard call — many projects keep the Discussion open and link the Issue back, so the rationale stays discoverable. If the org has decided to close them, fine; if not, "a maintainer marks the Discussion accepted and opens a tracking Issue linked back to it" is closer to common practice.

This is purely a wording suggestion and depends on what GOVERNANCE.md (in the related PR) actually says — please make sure the two documents agree on this point so contributors don't get conflicting instructions.

Nits (optional)

• The blockquote callout uses > for two lines; rendering on GitHub will wrap them as a single quoted paragraph. That's fine, but if the intent is two visually distinct lines, add a blank > line between them (> \n> syntax) or put them in separate quoted blocks.
• Step 1 ends "…and alternatives you considered." — drop the "you considered" or align with the original text "any alternatives you've considered" for consistency with the bug-report bullet style above.

Verdict

Content of the change is good and aligned with the new governance direction. The only material concern is the GOVERNANCE.md link being live before community#2 merges; resolving the merge order (or pinning the link) closes it. The other items are cleanups that would improve clarity but don't block.

Posting as COMMENTED so the merge-order point is acknowledged before this lands; I'd happily flip to APPROVE once community#2 is queued ahead of this one (or the link is temporarily pinned to the PR branch).

[lml2468]

Thanks @yujiawei for the review!

All items addressed in the amended commit:

P1 — GOVERNANCE.md link 404 risk
Added a note in the PR description to merge community#2 first. The link itself now also mirrors the approach: once community#2 lands on main, the link will resolve correctly. Merge order: community PR #2 → this PR.

P2 — Bridge with "Issue or Discussion?" (top section)
Tightened the top-of-file bullet from "concrete feature request" to "small, concrete feature request" so the two sections no longer give conflicting guidance. Added a bridging sentence in "Suggesting Features": "This refines the Issue or Discussion? rule above: even a concrete feature request that is significant in scope should start as a Discussion."

P2 — Define "significant" vs "minor"
Added an explicit heuristic: "Roughly: anything that changes a public API, adds a new user-facing concept, affects more than one repository, or has notable UX or architectural implications. Bug-adjacent improvements, small ergonomic wins, and documentation changes are 'minor'."

P2 — Step 3 wording
Changed "A maintainer closes the Discussion" to "The Project Lead marks the outcome" and "closes as accepted and opens a tracking Issue linked back to it" — consistent with GOVERNANCE.md's Accepted/Declined/Deferred table.

Nit — Step 1 wording
Aligned with the Discussion template field names for consistency.

[yujiawei]

Code Review — PR #9 (.github)

Summary

Documentation-only change to CONTRIBUTING.md. Replaces the old one-liner under Suggesting Features with a 4-step Discussion-first flow, and tightens the top-of-doc "Open an Issue when" rule for feature requests to "small, concrete" / no cross-repo impact. The intent is clear, the writing is good, and the process described is sensible.

Verdict: Commented — content reads well; one cross-repo sequencing risk and a few minor consistency nits worth addressing before merge.

1. Verification

Item	Status	Evidence
Diff scope matches PR description (only CONTRIBUTING.md, +15/−5)	✅	gh pr diff 9 confirms a single-file change
Linked Ideas Discussion category exists	✅	Mininglamp-OSS/community Discussion category ideas is present
Feature Request issue template still referenced and exists	✅	Mininglamp-OSS/.github/ISSUE_TEMPLATE/feature_request.yml present
Linked GOVERNANCE.md exists at the URL given	❌	https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md returns 404 — that file is still in open PR Mininglamp-OSS/community#2 (not merged)
Octo Board link points to a real location	✅	https://github.com/orgs/Mininglamp-OSS/projects is the org projects page
Markdown renders cleanly	✅	Blockquote, ordered list, and bold all parse correctly

2. Findings

P1 — Cross-repo link to a file that does not yet exist on main

CONTRIBUTING.md (post-merge) will link to:

https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md

That file is currently only on the docs/add-governance branch via Mininglamp-OSS/community#2, which is still open. If this PR (#9) merges before community #2, the link is a hard 404 for the entire window between the two merges. That is the most user-visible failure mode of the new process — a contributor reading the new instructions and clicking the canonical "full process" link will hit a dead page.

Recommendation: make merge order explicit. Either

1. Block this PR until community#2 is merged (preferred — single source of truth becomes real before it is advertised), or
2. Land community#2 first in the same review session and only then merge this PR.

A merge-queue ordering note in the PR description would also be enough.

P2 — Top-of-doc rule does not mention "significant features → Discussion"

The "Issue or Discussion?" guide near the top of CONTRIBUTING.md gets a tighter Issue rule (good), but the parallel "Open a Discussion when:" list is left unchanged. After this PR, the canonical rule for significant features is "open a Discussion", but the only place that says so is several screens down in Suggesting Features. A reader who only consults the top-of-doc decision guide can still miss the rule.

Recommendation: add one bullet to the "Open a Discussion when:" list, e.g.

- You have a **significant feature idea** — changes a public API, adds a new user-facing concept, affects more than one repo, or has notable UX/architectural impact → [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas)

This keeps the top-of-doc guide self-sufficient and matches the wording later in Suggesting Features.

P2 — Significance criteria worded two different ways

The "Issue or Discussion?" rule defines small as: "well-scoped, no API or cross-repo impact" (CONTRIBUTING.md:11).

Suggesting Features defines significant as: "changes a public API, adds a new user-facing concept, affects more than one repository, or has notable UX or architectural implications" (CONTRIBUTING.md:93).

These should be the inverse of each other but the top version omits the user-facing-concept and UX/architectural axes. Readers comparing the two will assume the difference is intentional ("ah, UX-only changes go through the Issue path because the top guide doesn't list them"), which is the opposite of the intended policy.

Recommendation: unify the criteria — pick the longer list, then either repeat it in both places or have one section refer to the other instead of paraphrasing.

P3 — Mild redundancy in the new section's intro

Lines 81–86 (post-PR) say almost the same thing twice:

> **Significant features require a Discussion before an Issue.**
> This refines the [Issue or Discussion?](#issue-or-discussion) rule above…

Octo follows a **Discussion-first** approach for significant features:

The blockquote is already a strong topic sentence; the following paragraph mostly restates it before launching the numbered steps. Consider collapsing to one of the two — either keep the blockquote as the lead-in and start step 1 directly, or drop the blockquote and let the body paragraph carry the rule.

P3 — Process gap: no described path for "rejected" outcomes

Step 3 only describes the accepted branch:

The Project Lead marks the outcome. Once consensus is reached, the Discussion is closed as accepted and a tracking Issue is opened…

What happens to a Discussion that does not reach consensus, is declined, or is parked? Probably this is covered in GOVERNANCE.md, in which case a one-line pointer is enough ("declined / parked outcomes are described in GOVERNANCE.md"). But as written, a contributor whose Discussion goes nowhere has no closing instruction.

P3 — "Project Lead" is referenced but not defined here

The role appears twice in the new copy without definition. Acceptable if GOVERNANCE.md defines it (the link is right there), but the role name is currently load-bearing in this file with no inline gloss. A short parenthetical such as "the Project Lead (see GOVERNANCE.md)" on first use would make the document stand on its own.

3. Suggestions (non-blocking)

• The "Not sure which path to take?" closing line is a nice touch; consider mirroring it at the top of the Issue or Discussion? section as well, so the same advice is reachable from both entry points.
• The "Ideas" category link includes the full URL form; consider using the same shortened anchor style used elsewhere in the file for consistency, or — fine to leave as-is.

4. Additional observations

• No CI / status-check changes are required by this PR; it is doc-only.
• No risk to existing in-flight Issues — the change does not retroactively reroute anything.
• The "Bug Report" section (unchanged) still uses the older imperative-bullet style. Not in this PR's scope, but a future polish pass could harmonize tone with the new Suggesting Features prose.

TL;DR

Solid documentation change. Please address P1 (sequencing the cross-repo link so GOVERNANCE.md exists on main before this lands) and ideally P2 (top-of-doc Discussion rule + unified significance criteria) before merge. The rest is polish.

[yujiawei]

Code Review — PR #9 (.github)

Summary

Documentation-only change to CONTRIBUTING.md. Replaces the old one-liner under Suggesting Features with a 4-step Discussion-first flow, and tightens the top-of-doc "Open an Issue when" rule for feature requests to "small, concrete" / no cross-repo impact. The intent is clear, the writing is good, and the process described is sensible.

Verdict: Commented — content reads well; one cross-repo sequencing risk and a few minor consistency nits worth addressing before merge.

1. Verification

Item	Status	Evidence
Diff scope matches PR description (only CONTRIBUTING.md, +15/−5)	✅	gh pr diff 9 confirms a single-file change
Linked Ideas Discussion category exists	✅	Mininglamp-OSS/community Discussion category ideas is present
Feature Request issue template still referenced and exists	✅	Mininglamp-OSS/.github/ISSUE_TEMPLATE/feature_request.yml present
Linked GOVERNANCE.md exists at the URL given	❌	https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md returns 404 — that file is still in open PR Mininglamp-OSS/community#2 (not merged)
Octo Board link points to a real location	✅	https://github.com/orgs/Mininglamp-OSS/projects is the org projects page
Markdown renders cleanly	✅	Blockquote, ordered list, and bold all parse correctly

2. Findings

P1 — Cross-repo link to a file that does not yet exist on main

CONTRIBUTING.md (post-merge) will link to:

https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md

That file is currently only on the docs/add-governance branch via Mininglamp-OSS/community#2, which is still open. If this PR (#9) merges before community #2, the link is a hard 404 for the entire window between the two merges. That is the most user-visible failure mode of the new process — a contributor reading the new instructions and clicking the canonical "full process" link will hit a dead page.

Recommendation: make merge order explicit. Either

1. Block this PR until community#2 is merged (preferred — single source of truth becomes real before it is advertised), or
2. Land community#2 first in the same review session and only then merge this PR.

A merge-queue ordering note in the PR description would also be enough.

P2 — Top-of-doc rule does not mention "significant features → Discussion"

The "Issue or Discussion?" guide near the top of CONTRIBUTING.md gets a tighter Issue rule (good), but the parallel "Open a Discussion when:" list is left unchanged. After this PR, the canonical rule for significant features is "open a Discussion", but the only place that says so is several screens down in Suggesting Features. A reader who only consults the top-of-doc decision guide can still miss the rule.

Recommendation: add one bullet to the "Open a Discussion when:" list, e.g.

- You have a **significant feature idea** — changes a public API, adds a new user-facing concept, affects more than one repo, or has notable UX/architectural impact → [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas)

This keeps the top-of-doc guide self-sufficient and matches the wording later in Suggesting Features.

P2 — Significance criteria worded two different ways

The "Issue or Discussion?" rule defines small as: "well-scoped, no API or cross-repo impact" (CONTRIBUTING.md:11).

Suggesting Features defines significant as: "changes a public API, adds a new user-facing concept, affects more than one repository, or has notable UX or architectural implications" (CONTRIBUTING.md:93).

These should be the inverse of each other but the top version omits the user-facing-concept and UX/architectural axes. Readers comparing the two will assume the difference is intentional ("ah, UX-only changes go through the Issue path because the top guide doesn't list them"), which is the opposite of the intended policy.

Recommendation: unify the criteria — pick the longer list, then either repeat it in both places or have one section refer to the other instead of paraphrasing.

P3 — Mild redundancy in the new section's intro

Lines 81–86 (post-PR) say almost the same thing twice:

> **Significant features require a Discussion before an Issue.**
> This refines the [Issue or Discussion?](#issue-or-discussion) rule above…

Octo follows a **Discussion-first** approach for significant features:

The blockquote is already a strong topic sentence; the following paragraph mostly restates it before launching the numbered steps. Consider collapsing to one of the two — either keep the blockquote as the lead-in and start step 1 directly, or drop the blockquote and let the body paragraph carry the rule.

P3 — Process gap: no described path for "rejected" outcomes

Step 3 only describes the accepted branch:

The Project Lead marks the outcome. Once consensus is reached, the Discussion is closed as accepted and a tracking Issue is opened…

What happens to a Discussion that does not reach consensus, is declined, or is parked? Probably this is covered in GOVERNANCE.md, in which case a one-line pointer is enough ("declined / parked outcomes are described in GOVERNANCE.md"). But as written, a contributor whose Discussion goes nowhere has no closing instruction.

P3 — "Project Lead" is referenced but not defined here

The role appears twice in the new copy without definition. Acceptable if GOVERNANCE.md defines it (the link is right there), but the role name is currently load-bearing in this file with no inline gloss. A short parenthetical such as "the Project Lead (see GOVERNANCE.md)" on first use would make the document stand on its own.

3. Suggestions (non-blocking)

• The "Not sure which path to take?" closing line is a nice touch; consider mirroring it at the top of the Issue or Discussion? section as well, so the same advice is reachable from both entry points.
• The "Ideas" category link includes the full URL form; consider using the same shortened anchor style used elsewhere in the file for consistency, or — fine to leave as-is.

4. Additional observations

• No CI / status-check changes are required by this PR; it is doc-only.
• No risk to existing in-flight Issues — the change does not retroactively reroute anything.
• The "Bug Report" section (unchanged) still uses the older imperative-bullet style. Not in this PR's scope, but a future polish pass could harmonize tone with the new Suggesting Features prose.

TL;DR

Solid documentation change. Please address P1 (sequencing the cross-repo link so GOVERNANCE.md exists on main before this lands) and ideally P2 (top-of-doc Discussion rule + unified significance criteria) before merge. The rest is polish.

[lml2468]

Hey @yujiawei — community PR #2 has been merged. The GOVERNANCE.md link in this PR now resolves correctly on main.

Could you take another look when you get a chance? All your previous feedback has been addressed. Happy to make any further adjustments 🙏

[lml2468]

Review Feedback Resolution (1496da6)

Addressed remaining P2/P3 items from the 2nd/3rd review rounds by @yujiawei:

P2 — Top-of-doc "Open a Discussion when:" missing significant features

Added new bullet: "You have a significant feature idea — changes a public API, adds a new user-facing concept, affects more than one repo, or has notable UX/architectural impact → Ideas"

The decision guide is now self-sufficient — a reader consulting only the top-of-doc section will see the Discussion-first rule without needing to scroll to Suggesting Features.

P2 — Significance criteria unified

Removed "Roughly:" hedge from the definition. Both sections now use the same four-axis test (public API, user-facing concept, cross-repo, UX/architectural). Top-of-doc says "well-scoped, no API or cross-repo impact" for the Issue path (inverse of the significance criteria).

P3 — Redundancy in intro removed

Dropped the bridging sentence ("This refines the Issue or Discussion? rule above...") and the restating paragraph ("Octo follows a Discussion-first approach..."). The blockquote now leads directly into the numbered steps.

P3 — Declined/deferred outcomes documented

Step 3 now covers all three outcomes: "Accepted Discussions are converted to a tracking Issue... Declined or deferred outcomes are recorded in the Discussion with a rationale — see GOVERNANCE.md for the full decision table."

P3 — "Project Lead" defined on first use

Step 2 now includes a parenthetical link: "the Project Lead (see GOVERNANCE.md)" so the role is traceable without leaving this document.

Previously addressed (confirmed present)

• ✅ P1 GOVERNANCE.md link — community#2 merged, link resolves
• ✅ "Small, concrete" tightening in top-of-doc Issue rule
• ✅ Step 3 aligned with GOVERNANCE.md terminology
• ✅ "Not sure?" closing line retained

[yujiawei]

Code Review — PR #9 (.github)

Summary

Replaces the one-line "use the Feature Request template" guidance in CONTRIBUTING.md with a four-step Discussion-first process, and splits the "Issue vs Discussion" guide to differentiate small vs significant feature requests. The change is small (+13 / −5, single file) and accurately mirrors the governance model defined in community/GOVERNANCE.md.

Verdict: COMMENTED — content is correct and ships cleanly. A few non-blocking nits below.

1. Verification

Item	Result	Evidence
GOVERNANCE.md exists in community/main	✅	gh api repos/Mininglamp-OSS/community/contents/GOVERNANCE.md returns 6,658 bytes
Ideas discussion category exists in community	✅	GraphQL discussionCategories returns Ideas (slug ideas)
"Project Lead" role referenced is defined upstream	✅	GOVERNANCE.md § Maintainers documents the Project Lead role and authority
Four-step flow matches GOVERNANCE.md Mermaid flowchart	✅	Discussion → consensus → tracking Issue → Octo Board → implementation matches GOVERNANCE.md § Feature Development Process
"Structured template is pre-filled automatically" claim	✅	Asserted in GOVERNANCE.md § How to Write a Feature Discussion (same wording) — consistent across docs
Cross-links work	✅	All three GOVERNANCE.md links resolve; both Ideas category links resolve
No public-API / behavior change	✅	Doc-only change

2. Findings

P2 — Open a Discussion when: list now has two overlapping entries pointing at Ideas

CONTRIBUTING.md lines 14–16 (post-PR):

- You have a **significant feature idea** — changes a public API, … → [Ideas](…/categories/ideas)
- You have an **early-stage idea** to share → [Ideas](…/categories/ideas)

Both bullets now route to the same Ideas category, and a reader with a fully-formed significant idea matches the first bullet, while a reader with a half-baked significant idea matches both. The distinction between "early-stage" and "significant" is orthogonal (maturity vs scope), so the current ordering reads as if they were mutually exclusive when they aren't. Consider one of:

• Merge into a single bullet: "You have a feature idea — early-stage exploration or a significant proposal (public API change, cross-repo impact, notable UX/architecture) → Ideas"
• Or keep both bullets but add a parenthetical to disambiguate, e.g. "…early-stage idea to share (not yet a concrete proposal) → Ideas".

Not blocking — the downstream Suggesting Features section disambiguates clearly.

P2 — GOVERNANCE.md is linked three times in the same ~8-line block

CONTRIBUTING.md lines 83, 84, and 87 (post-PR) all link to GOVERNANCE.md. Two are inside list items, one is in the blockquote above. The third occurrence ("see GOVERNANCE.md for the full decision table") is arguably the only one carrying new information; the other two could be folded into the leading blockquote without loss. This is cosmetic but reduces visual noise.

P2 — Curly quote in "significant" is inconsistent with the rest of the file

Line 95 (post-PR) uses U+201C/U+201D smart quotes around “significant” and “minor”, while the rest of CONTRIBUTING.md (including pre-PR "why" on line 51 and the diff's own **reproducible bug** style) uses straight ASCII characters. Not a functional problem, but inconsistent typography across the same doc.

P3 — "Bug-adjacent improvements" is slightly awkward phrasing

Line 95 (post-PR): "Bug-adjacent improvements, small ergonomic wins, and documentation changes are 'minor'…". GOVERNANCE.md uses the cleaner phrasing "Minor improvements, bug fixes, small ergonomic wins, and documentation updates…" (§ What Requires a Discussion?). Aligning the two would make the docs feel like they were written together.

3. Suggestions

1. (Optional) Tighten the Open a Discussion when: list to resolve the overlap above.
2. (Optional) Collapse the three GOVERNANCE.md links to one or two within the Suggesting Features section.
3. (Optional) Use straight quotes for "significant" / "minor" and reuse the GOVERNANCE wording for the minor-features sentence so the two documents stay in sync verbatim.

None of these block merging; they are polish items the author can take or leave.

4. Additional Observations

• The change correctly preserves the escape hatch ("minor features may still be filed directly as Issues using the Feature Request template"), which keeps the day-to-day flow unblocked for triage-friendly work. Good.
• The 4-step list uses bold lead-ins consistent with the existing voice of the file (cf. "Pull Request Guidelines" section).
• No changes are needed in sibling .github files: there is no template that contradicts the new flow, and the existing Feature Request template remains a valid landing spot for "minor" requests.
• Worth a follow-up (not in this PR): the project READMEs for octo-server / octo-web could link to this section so contributors discover the Discussion-first path from the per-repo docs as well. Out of scope here.

[lml2468]

Re-review feedback addressed (0a18f93)

P2 — Overlapping Ideas entries merged: Combined "significant feature idea" and "early-stage idea" into a single bullet: "You have a feature idea — early-stage exploration or a significant proposal (public API change, cross-repo impact, new user-facing concept, notable UX/architecture) → Ideas". No more ambiguity about which bullet applies.

P2 — GOVERNANCE.md over-linking: Reduced from 3 links to 1 within the Suggesting Features section. The blockquote reference is the canonical link; steps 2 and 3 no longer repeat it.

P2 — Curly quotes: Replaced \u201c/\u201d smart quotes with straight ASCII " to match the rest of the file.

P3 — "Bug-adjacent" phrasing: Aligned with GOVERNANCE.md wording: "Minor improvements, bug fixes, small ergonomic wins, and documentation updates".

[yujiawei]

Code Review — PR #9 (.github)

Summary

Solid documentation update. The new "Suggesting Features" section is internally consistent with the top-of-doc "Issue or Discussion?" guide, the external links resolve correctly, and the escape hatch for small changes is preserved so this does not raise the bar for trivial contributions.

Verdict: COMMENTED — non-blocking suggestions only.

What works well

• End-to-end consistency. The narrowed Issue bullet (L11: "small, concrete feature request — well-scoped, no API or cross-repo impact") and the expanded Discussion bullet (L15) match the four-step process and "What counts as significant?" definition in the new section (L81-L91). A reader who only reads the top of the file gets the same answer as one who reads the full section.
• External references are valid.
  • GOVERNANCE.md exists at the linked path (community PR #2 merged 2026-05-14).
  • The Ideas discussion category exists in Mininglamp-OSS/community.
  • Mininglamp-OSS/community/.github/DISCUSSION_TEMPLATE/feature_request.md exists, so "A structured template is pre-filled automatically" (L84) is accurate.
  • Mininglamp-OSS/.github/ISSUE_TEMPLATE/feature_request.yml exists, so the Feature Request template referenced in L89 is a real template.
• Markdown renders cleanly. The blockquote callout, ordered list, and bold emphasis all parse correctly; no broken anchors.
• Escape hatch preserved. Small/minor features still go straight to Issues, which prevents the new process from feeling heavyweight for trivial contributions.

Suggestions (non-blocking)

S1. L89 — "bug fixes" and "documentation updates" don't belong under the Feature Request template

"Minor improvements, bug fixes, small ergonomic wins, and documentation updates may be filed directly as Issues using the Feature Request template."

The intent is clearly "don't force a Discussion for tiny things," but the wording lumps two categories under the wrong template:

• Bug fixes are already covered by the "Reporting Bugs" section (L72-L77), which directs users to the Bug Report template. Telling readers to file bug fixes under the Feature Request template contradicts that and would route bug reports to the wrong template.
• Documentation updates are typically PRs, not Issues — and if they are filed as Issues, the Feature Request template fields (problem / proposed solution / alternatives) are a poor fit.

Suggested rewording:

"Small ergonomic improvements and minor enhancements may be filed directly as Issues using the Feature Request template. Bug reports go to the Bug Report template (see Reporting Bugs above); documentation fixes can be opened as a PR directly."

This keeps the escape hatch but stops cross-wiring readers to the wrong template.

S2. L15 — the Discussion bullet is dense

The combined "feature idea — early-stage exploration or a significant proposal (public API change, cross-repo impact, new user-facing concept, notable UX/architecture)" packs five distinct criteria into one parenthetical. Readers skimming the guide may bounce off it.

Optional split:

- You have an **early-stage idea** to share → [Ideas](.../ideas)
- You have a **significant feature proposal** (public API, cross-repo, new user-facing concept, notable UX/architecture) → [Ideas](.../ideas)

Same destination, lower cognitive load. Purely a style call — fine to keep as-is if you prefer the single-bullet density.

S3. L86 — define "Project Lead" inline or hyperlink the term

L86 introduces "Project Lead" as a decision-making role with no inline definition. New contributors who don't follow the link will not know who that is or how to reach them. The role is defined in GOVERNANCE.md, so a hyperlink on first mention would close the loop without adding text:

"The Project Lead marks the outcome. …"

(Assuming the anchor in GOVERNANCE.md is #project-lead — adjust to whatever the actual heading slug is.)

S4. Minor — L84 "in the relevant repository" vs. L84 "of the community repository"

L84 says the Discussion is opened in the community repository; L86 says the resulting Issue lands "in the relevant repository." That is correct and intentional, but a first-time reader may briefly wonder why the home moves. A short parenthetical on L86 ("the repository the feature would ship in") would make the transition explicit. Very minor.

Items verified

Check	Status
Diff scope matches PR title/description	✅
Top-of-doc guide consistent with new section	✅
GOVERNANCE.md link resolves	✅
Ideas discussion category exists	✅
Discussion feature_request.md template exists	✅
Issue feature_request.yml template exists	✅
Bug Report flow unchanged	✅
No conflicts with sibling sections (Branch Naming, Commit Messages, PR Guidelines, Code of Conduct)	✅
Escape hatch for small contributions preserved	✅
Cross-repo impact: .github defaults apply org-wide; per-repo CONTRIBUTING.md (if any) may shadow this	⚠️ informational — out of scope for this PR

Recommendation

Approve after addressing S1 (the bug-fix / docs wording in L89 is a real misdirection, not a style nit). S2-S4 are optional polish.