From 420f116c8b1f5f2c38931d2a5da6ef09b3f03162 Mon Sep 17 00:00:00 2001 From: merlin Date: Thu, 14 May 2026 12:04:50 +0800 Subject: [PATCH 1/3] docs: update Suggesting Features section with Discussion-first process --- CONTRIBUTING.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc55c48..497a63f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ Not sure whether to open an Issue or a Discussion? Use this guide: ### Open an Issue when: - You found a **reproducible bug** — include version, environment, and steps to reproduce -- You have a **concrete feature request** — need is clearly defined with a specific use case +- You have a **small, concrete feature request** — well-scoped, no API or cross-repo impact ### Open a Discussion when: - You have a **usage question** or need help → [Q&A](https://github.com/Mininglamp-OSS/community/discussions/categories/q-a) @@ -78,10 +78,20 @@ Use the repository's **Bug Report** issue template. Include: ## Suggesting Features -Use the repository's **Feature Request** issue template. Describe: -- The problem you're trying to solve -- Your proposed solution -- Any alternatives you've considered +> **Significant features require a Discussion before an Issue.** +> This refines the [Issue or Discussion?](#issue-or-discussion) rule above: even a concrete feature request that is significant in scope should start as a Discussion. +> See [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full process. + +Octo follows a **Discussion-first** approach for significant features: + +1. **Open a Discussion** in the [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) category of the community repository. A structured template is pre-filled automatically. Describe the problem, your proposed solution, and alternatives you considered. +2. **Discuss and refine.** Community members and the Project Lead will provide feedback. Iterate until there are no unresolved blocking concerns. +3. **The Project Lead marks the outcome.** Once consensus is reached, the Discussion is closed as *accepted* and a tracking Issue is opened in the relevant repository, linked back to the Discussion. +4. **The Issue is scheduled** on the [Octo Board](https://github.com/orgs/Mininglamp-OSS/projects) and implementation begins. + +**What counts as "significant"?** 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" and may be filed directly as Issues using the **Feature Request** template. + +Not sure which path to take? Open a Discussion — the Project Lead will guide you. ## Code of Conduct From 1496da68728b1e4035c82d58de038b76b2632fbd Mon Sep 17 00:00:00 2001 From: wangdachui-bot Date: Sun, 17 May 2026 21:45:08 +0800 Subject: [PATCH 2/3] docs: address review P2/P3 feedback on Suggesting Features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P2 — Add 'significant feature idea' bullet to top-of-doc 'Open a Discussion when' list so the decision guide is self-sufficient. P2 — Unify significance criteria: remove 'Roughly:' hedge from the definition; both top-of-doc and Suggesting Features sections now use the same four-axis test (public API, user-facing concept, cross-repo, UX/architectural). P3 — Remove redundant intro paragraph ('Octo follows a Discussion-first approach...') and bridging sentence to reduce repetition. P3 — Step 3 now covers declined/deferred outcomes with a pointer to GOVERNANCE.md's decision table, not just the accepted path. P3 — 'Project Lead' on first use now links to GOVERNANCE.md so the role is defined for readers who haven't seen that document. --- CONTRIBUTING.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 497a63f..60729f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,7 @@ Not sure whether to open an Issue or a Discussion? Use this guide: ### Open a Discussion when: - You have a **usage question** or need help → [Q&A](https://github.com/Mininglamp-OSS/community/discussions/categories/q-a) +- 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) - You have an **early-stage idea** to share → [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) - You built something with Octo → [Show and tell](https://github.com/Mininglamp-OSS/community/discussions/categories/show-and-tell) - You're not sure → open a Discussion; maintainers will convert it to an Issue if needed @@ -79,17 +80,14 @@ Use the repository's **Bug Report** issue template. Include: ## Suggesting Features > **Significant features require a Discussion before an Issue.** -> This refines the [Issue or Discussion?](#issue-or-discussion) rule above: even a concrete feature request that is significant in scope should start as a Discussion. > See [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full process. -Octo follows a **Discussion-first** approach for significant features: - 1. **Open a Discussion** in the [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) category of the community repository. A structured template is pre-filled automatically. Describe the problem, your proposed solution, and alternatives you considered. -2. **Discuss and refine.** Community members and the Project Lead will provide feedback. Iterate until there are no unresolved blocking concerns. -3. **The Project Lead marks the outcome.** Once consensus is reached, the Discussion is closed as *accepted* and a tracking Issue is opened in the relevant repository, linked back to the Discussion. +2. **Discuss and refine.** Community members and the Project Lead (see [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md)) will provide feedback. Iterate until there are no unresolved blocking concerns. +3. **The Project Lead marks the outcome.** Accepted Discussions are converted to a tracking Issue in the relevant repository, linked back to the Discussion. Declined or deferred outcomes are recorded in the Discussion with a rationale — see [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full decision table. 4. **The Issue is scheduled** on the [Octo Board](https://github.com/orgs/Mininglamp-OSS/projects) and implementation begins. -**What counts as "significant"?** 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" and may be filed directly as Issues using the **Feature Request** template. +**What counts as “significant”?** 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” and may be filed directly as Issues using the **Feature Request** template. Not sure which path to take? Open a Discussion — the Project Lead will guide you. From 0a18f93a92345d804b7dea1dd8f4e88c5a4461cc Mon Sep 17 00:00:00 2001 From: wangdachui-bot Date: Sun, 17 May 2026 21:54:23 +0800 Subject: [PATCH 3/3] docs: resolve re-review feedback on Suggesting Features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P2 — Merge overlapping Ideas bullets into single entry covering both early-stage exploration and significant proposals, eliminating the ambiguity between the two. P2 — Reduce GOVERNANCE.md links from 3 to 1 within the Suggesting Features section (the blockquote reference is sufficient; steps 2-3 no longer repeat the link). P2 — Replace curly quotes with straight ASCII quotes for consistency with the rest of the file. P3 — Align 'minor features' phrasing with GOVERNANCE.md wording: 'Minor improvements, bug fixes, small ergonomic wins, and documentation updates' instead of 'Bug-adjacent improvements'. --- CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60729f3..8ed0e3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,8 +12,7 @@ Not sure whether to open an Issue or a Discussion? Use this guide: ### Open a Discussion when: - You have a **usage question** or need help → [Q&A](https://github.com/Mininglamp-OSS/community/discussions/categories/q-a) -- 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) -- You have an **early-stage idea** to share → [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) +- 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](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) - You built something with Octo → [Show and tell](https://github.com/Mininglamp-OSS/community/discussions/categories/show-and-tell) - You're not sure → open a Discussion; maintainers will convert it to an Issue if needed @@ -83,11 +82,11 @@ Use the repository's **Bug Report** issue template. Include: > See [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full process. 1. **Open a Discussion** in the [Ideas](https://github.com/Mininglamp-OSS/community/discussions/categories/ideas) category of the community repository. A structured template is pre-filled automatically. Describe the problem, your proposed solution, and alternatives you considered. -2. **Discuss and refine.** Community members and the Project Lead (see [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md)) will provide feedback. Iterate until there are no unresolved blocking concerns. -3. **The Project Lead marks the outcome.** Accepted Discussions are converted to a tracking Issue in the relevant repository, linked back to the Discussion. Declined or deferred outcomes are recorded in the Discussion with a rationale — see [GOVERNANCE.md](https://github.com/Mininglamp-OSS/community/blob/main/GOVERNANCE.md) for the full decision table. +2. **Discuss and refine.** Community members and the Project Lead will provide feedback. Iterate until there are no unresolved blocking concerns. +3. **The Project Lead marks the outcome.** Accepted Discussions are converted to a tracking Issue in the relevant repository, linked back to the Discussion. Declined or deferred outcomes are recorded with a rationale. 4. **The Issue is scheduled** on the [Octo Board](https://github.com/orgs/Mininglamp-OSS/projects) and implementation begins. -**What counts as “significant”?** 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” and may be filed directly as Issues using the **Feature Request** template. +**What counts as "significant"?** Anything that changes a public API, adds a new user-facing concept, affects more than one repository, or has notable UX or architectural implications. Minor improvements, bug fixes, small ergonomic wins, and documentation updates may be filed directly as Issues using the **Feature Request** template. Not sure which path to take? Open a Discussion — the Project Lead will guide you.