Skip to content

Feature requests start with consumer needs - #15

Merged
Marius Storhaug (MariusStorhaug) merged 9 commits into
mainfrom
feature-intake-alignment
Nov 11, 2026
Merged

Marius Storhaug (MariusStorhaug) merged 9 commits into
mainfrom
feature-intake-alignment

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Oct 31, 2026 •

Copy link
Copy Markdown
Member

Feature requesters describe their need, motivation, and expected result without choosing an implementation or learning a special scenario format. The shared form keeps its feature identity, routing, and one required free-text field.

Changed: Consumer-focused feature intake

The Describe the need field requests who benefits, the problem or opportunity, and a situation/action/result example. A failure or limit example is conditional. The introduction uses direct requests and states the feedback/internal-planning boundary as current fact. Technical Task/Bug plans, existing labels, native-type selection, and minimum submission requirements are unchanged.

Adopting this release

After merge, repositories that use this organization-owned form receive the prompts without consumer-local copies. No configuration, code, or invocation change is required. Local issue forms retain precedence and are not changed here. This public defaults repository does not publish a versioned release.

Release impact

This is a compatible, patch-level intake improvement. No versioned publisher applies and no version is produced. No live labels, release configuration, permissions, rulesets, or merge settings change.


Technical details

Consumer change record

Surface Before After Consumer action / verification
Organization feature form Required Description asks for implementation suggestions and alternatives. The same description field asks for consumer need, motivation, and observable examples. Name, title, labels, native-type absence, and required-field contract remain. No consumer edit. One-time YAML/interface, native rendering, and actual link checks are recorded below.

Template baseline

Head 9a4da3a0dacf7cfc68cad80270884886bcdc1ad9 targets main at 0c67251812ea306543f3a14ab473ae357cfb76ac. The final PR diff is one modified feature form: 17 additions, 7 deletions. No added test or validator remains.

The form is byte-for-byte equal to candidate 589285cfb6c2ecc761c5308de4527d2dd2c54bd4, with blob 19d6abbbf5b1a4a5b48ce5710be9f7e79f0be742. The latest commit removes only the 119-line added test suite; it changes no form content or behavior and no other source file.

The consumer guidance is published: MSXOrg/docs#230 merged on 2026-11-03 at 8c9d9353eb154d6072b3ed1d825a78d58a4665d3. The fixed writing baseline and official STE guidance govern the unchanged prose. Shipped links use the current canonical planning/routing pages, not an immutable review snapshot.

Maintainer evidence

Test-policy correction. The whole FeatureIntake.Tests.ps1 file was added by this PR. Its 12 cases froze checked-in YAML metadata, shape, phrases, URLs, or blank configuration; built-in Markdown conversion exercised no owned runtime. The current Testing rule prohibits those source-string and snapshot assertions. The user-directed review supersedes the earlier campaign limit on removing them. All 12 passed immediately before removal: this is conformance, not hiding a failing test. No owned-runtime coverage or conflicting content decision was found. There is no replacement test, validator, simulation, tooling, or configuration. No runtime suite remains and no current test pass is claimed. Earlier suite results and reviews are historical evidence for their stated commits only.

Fresh one-time checks. Configuration/reference results stay outside source. With $configuration naming the published default snapshot and $target.Path each named input:

Actual command / operation Result
python - (inline PyYAML interface and raw-byte inspection) 20 nodes, 6 mappings, 2 body elements, 1 required description textarea. All non-prose keys/order/types/values and blank configuration match the original base. The current form bytes exactly match 589285c.
yamllint --format parsable --config-file $configuration $target.Path; repeat with --strict All 6 runs (original 0c6725, prior 589285c, and current form; normal and strict) return exit 0 with 0 diagnostics. No baseline formatting change or weakened rule.
gh api --method POST markdown --input - with actual introduction, mode=gfm, context=MSXOrg/.github Native GitHub HTML renders exactly 2 canonical links.
python - (inline unauthenticated HTTPS/actual HTML inspection) 2 targets return HTTP 200: planning contains issue-planning; routing contains issue-hierarchy. Neither form link has a fragment.
git diff --name-status origin/main...HEAD; git diff --check Exactly one modified feature form; whitespace check passes.

YAML-default provenance: current Docs.yml selects Super-Linter 4ce20838b8ab83717e78138c5b3a1407148e0918 without a YAML override. Its published default, blob 2aa49bd1867e24acdea4172191922df6135b69c6, is used locally only. It is not installed repository CI or a nonexistent MSX YAML override. The configuration bytes match that source exactly. Its yamllint dependency pin is yamllint==1.38.0, matching the local tool.

These observations establish static interface preservation, rendered links, and actual page/anchor availability. They are not owned-runtime tests, GitHub form-submission end-to-end coverage, or hosted CI.

Changed surface Guidance / result
Feature form YAML, Natural Language, canonical planning/routing, and GitHub form schema checked; consumer content and routing preserved.
Removed added suite Current Testing prohibition applied by deletion; no source-shape test or replacement remains.

The existing Task plan and evidence are updated. Scoped convergence finds no additional fully delivered issue: #10 concerns community PR templates, #11/#12 hosted validation, #13 hooks, and #16/#17/#18 other campaign surfaces. Only #14 closes here. No new issue, CI/toolchain work, rule, or label is introduced.

Final review and native state. The explicitly requested current-head Copilot review is APPROVED at 9a4da3a0dacf7cfc68cad80270884886bcdc1ad9, with no active code issues or inline comments. All 5 submitted reviews were read: 4 historical COMMENTED reviews and this approval. Complete thread pagination reports 0 threads. GitHub now reports MERGEABLE/CLEAN and review decision APPROVED for the exact head/base above. The only check run is the successful copilot-pull-request-reviewer; there are 0 commit statuses, and the GraphQL rollup remains empty. No actually failing or named required check is reported. Organization defaults validation has not executed at this head: a successful reviewer check is not hosted form validation. Separate MSXOrg/.github#12 remains unmerged and is not revived here. Absent execution is not a pass.

Effective organization rules preserve squash-only integration, stale-review dismissal, code-owner review, last-push approval, and resolved threads. No named required-status-check rule is present. Those review/approval prerequisites are not waived by local checks or a Copilot run.

The PR remains open/non-draft. GitHub auto-merge and merge-queue entry are null. Agent merge remains enabled for review/CI/conflict maintenance with merge_pr=false; no settings changed. Root holds an exclusive global merge slot elsewhere. No merge is authorized in this session until that slot is handed off. No content decision is unresolved.

Relevant issues (or links)

Related work

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Maintainer confirmation is needed because frozen canonical-source correspondence and completed hosted validation for the actual head remain unverified.

No open issues 🎉

What changed in this PR

Updates the shared organization feature-request form to focus on consumer needs, motivation, and expected behavior without asking requesters to propose an implementation.

Changes:

  • Replaces implementation and alternatives prompts while preserving feature identity, triage labels, and one required description field.
  • Links canonical issue and planning guidance and clarifies that maintainers handle internal planning separately.
  • Adds Pester regression checks for form structure, routing, prompts, and rendered guidance links.
File Description
.github/​tests/​FeatureIntake.Tests.ps1 Adds regression checks for preserved intake behavior and consumer-focused guidance.
.github/​ISSUE_TEMPLATE/​10-feature.yml Rewrites feature prompts around needs and expected outcomes, with canonical guidance links.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Canonical guidance remains unmerged and hosted organization-defaults validation is incomplete, so maintainers must confirm publication and validation/enforcement readiness before landing.

No open issues 🎉

Review effort: Balanced

@MariusStorhaug

Marius Storhaug (MariusStorhaug) commented Nov 4, 2026 •

Copy link
Copy Markdown
Member Author

Historical record, superseded on 2026-11-11. This section records the writing candidates and checks at the specific 2026-11-04 commits. The entire added snapshot suite is removed at 9a4da3a0dacf7cfc68cad80270884886bcdc1ad9 under the current testing policy. No runtime tests remain and the 12/13-test results below are not current-head coverage or readiness. The current PR body and #14 contain the fresh one-file scope, static/rendering/link observations, and live merge prerequisites.

Writing alignment (2026-11-04)

The final persistent candidate is 589285cfb6c2ecc761c5308de4527d2dd2c54bd4. One small commit corrects the feature-form prose and coupled existing assertions; a second removes the newly introduced prose-freezing test after the pinned testing policy was verified. The final candidate retains only the original 12 tests, with no suite redesign. It applies the confirmed writing request within the existing #14 outcome; it adds no fields, policy, issue, dependency, or CI change.

Before After
“Thank you for suggesting a feature. Tell us what you need and what you expect to happen.” “Describe what you need and the result you expect.”
“Maintainers will link any internal planning work separately.” “Maintainers record internal plans in separate issues linked to the feedback.”
“What are you trying to do, and who would benefit?” “Describe what you need to do and who benefits.”
“Why does this matter?” / “What should happen?” “Explain why this matters.” / “Describe the expected behavior.”

The same need, motivation, situation/action/result example, conditional failure/limit example, no-technical-solution requirement, and canonical planning/routing links remain. The feedback/internal-planning boundary is a present-tense fact, not a future promise. Technical Task/Bug plans and source/validator integration boundaries are unchanged.

The writing sources are Natural Language and Technical Writing Guide at the fixed standards commit 1b0d4893c8fefabe604d04393068a8ff6f848082, plus the official STE FAQ guidance for direct imperative requests, active voice, and condition-first instructions. This is a targeted writing-practice correction, not a claim of full Issue 9 dictionary certification.

Before/after verification: the prior candidate 5edc236cf2bc365931483487a5a0d471b3779629 passes its 12 existing tests. The updated assertions ran before the form changed and produced exactly 7 passes and 6 intended failures across 13 tests, with no skips or failed discovery containers. The provisional writing candidate d879bd211cbc382bcc9f9c646ed8893ab4184aea passed 13 tests, including the subsequently removed prose-freezing test. That 7-pass/6-fail before-change result remains one-time review evidence, not a new permanent prose requirement. The final clean committed candidate 589285cfb6c2ecc761c5308de4527d2dd2c54bd4 passes the maintained 12 existing tests with 0 failures/skips/discovery failures. An independent recursive PyYAML comparison checks 20 nodes and 6 mappings and allows exactly two changed scalar values: the introduction and field description. Every key/order/type/metadata value, field ID/required flag, form identity, routing label/value, canonical URL, one-required-textarea constraint, and blank-issue configuration is unchanged.

Using the existing session-only runner/settings snapshots from immutable source 66f252776c102a0b94ab6619f61b121b89f0b174, with $tools referring to that snapshot directory:

Command Result
pwsh -NoProfile -File (Join-Path -Path $tools -ChildPath 'Invoke-PesterSuite.ps1') -Path '.github\tests' -RequiredVersion 6.1.0 Passed at the final candidate: 12 tests, 0 failures/skips/discovery failures, 1 suite.
yamllint --strict --config-file (Join-Path -Path $tools -ChildPath '.yaml-lint.yml') '.github\ISSUE_TEMPLATE\10-feature.yml' Passed.
Invoke-ScriptAnalyzer -Path '.github\tests\FeatureIntake.Tests.ps1' -Settings (Join-Path -Path $tools -ChildPath '.powershell-psscriptanalyzer.psd1') Passed: 0 diagnostics.
git --no-pager diff --check 5edc236cf2bc365931483487a5a0d471b3779629 HEAD Passed; exactly the feature form and its coupled suite change.

The explicitly requested final-head Copilot review covers 589285cfb6c2ecc761c5308de4527d2dd2c54bd4: COMMENTED, no open code issues, and zero inline comments. Its complete summary says source-publication and hosted validation/enforcement gates require maintainer confirmation; local checks and automated review do not establish readiness. Earlier review/readiness statements in the PR body describe the prior candidate, not this new head. This wording correction does not re-audit or bypass source/validator integration requirements.

The PR remains open and non-draft, as it was before this correction. GitHub autoMergeRequest remains null. No PR-state or merge-setting change was made.
Testing-policy correction and inherited limitation: Testing.md at the fixed standards source forbids adding tests whose only purpose is required prose phrases, source-string searches, or snapshots that freeze implementation shape. The newly added direct-request/no-thanks It block is removed in 589285cfb6c2ecc761c5308de4527d2dd2c54bd4; its earlier result is retained only as one-time review evidence. The inherited exact-text/structural suite also has a known tension with that policy. This user-directed campaign permits only tightly coupled maintenance of the existing suite, not a redesign or a new issue. The green 12-test result establishes that the maintained checks pass; it is not full testing-standard alignment, functional GitHub form end-to-end coverage, or proof of hosted readiness. Earlier general alignment statements in the PR body must not be interpreted as a fresh claim against this pinned rule.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Maintainers must confirm hosted validation for the current PR head and resolve the outstanding canonical-source publication and enforcement readiness gates, which static review alone cannot verify.

No open issues 🎉

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Maintainers must confirm source-publication and hosted validation/enforcement gates because the current head lacks the Organization defaults validation check, and local checks and automated review do not establish readiness.

No open issues 🎉

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟢 Approved

No active review issues remain for the consumer-focused feature request form update.

No open issues 🎉

Review effort: Balanced

@MariusStorhaug Marius Storhaug (MariusStorhaug) changed the title 🩹 [Patch]: Feature requests start with consumer needs Feature requests start with consumer needs Nov 11, 2026
@MariusStorhaug
Marius Storhaug (MariusStorhaug) merged commit d9dbfac into main Nov 11, 2026
1 check passed
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the feature-intake-alignment branch November 11, 2026 17:40
Marius Storhaug (MariusStorhaug) added a commit that referenced this pull request Nov 11, 2026
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->

The bug, patch, and general issue forms name the information that
reporters give. Their prompts use direct instructions without filler or
a promise of a fast response. Existing fields and submission
requirements do not change.

<!-- ANNOUNCEMENT STOP -->

<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->

## Changed: Issue forms use direct input instructions

The bug form identifies expected and actual behavior, the environment,
reproduction steps, related information, and evidence. The patch form
asks for the existing content or behavior and the desired change. The
general form asks for the issue subject and related information.

All three forms retain their names, titles, labels, field IDs, field
order, types, and required flags. The bug form keeps three required and
two optional textareas. The patch and general forms each keep one
required textarea. Repositories that use these shared forms need no
configuration change.

---
<details>
<summary>Technical details</summary>

<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->

**Source and plan:** Fresh preparation on 2026-11-11 verifies head
`deb2e80d65c1334a140c2f8c15eae738329542fb` against live `main` base and
merge base `0c67251812ea306543f3a14ab473ae357cfb76ac`. Remote refs
match. No source changes occur during this preparation; the worktree is
clean. The draft opened after bug-form commit
`e3e59ac00134eaec301506e2f01492d90faead9b`; the second small commit
completes patch and general intake. All five delivery-plan steps are
complete. #16 stays open until merge.

**Before and after:** All three introductions asked for "as much
information as possible" and promised quick help. Each now states the
information its form records. The field wording also becomes specific:

| Field | Before | After |
| --- | --- | --- |
| Bug description | A clear and concise description of what the bug is
vs. what you expected to happen. | Give the expected behavior and the
actual behavior. |
| Bug environment | What version, commit, platform, or configuration
were you using when the problem occurred? | Give the version, commit,
platform, or configuration in use when the problem occurred. |
| Patch description | A clear and concise description of what you would
want to change. | Give the existing content or behavior and the change
you want. |
| General description | A clear and concise description. | Give the
subject of the issue and the related information. |

The original pre-edit, one-time wording checks reported 3 values passing
and 7 failing; all 10 passed after implementation. Fresh manual review
covers all three forms, all 10 changed prose values, and the complete
diff. It confirms the accepted requested-information meaning and direct
en-US instructions. The environment prompt retains `or`; it does not
require every listed environment value. No content decision remains.

**Fresh lint provenance:** This repository has no YAML lint
configuration or installed hosted validation. Both fixed MSX docs source
`1b0d4893c8fefabe604d04393068a8ff6f848082` and current source
`f9b335d0b78a3eead0b7efa573936e86cb1e7265` use Docs workflow blob
`de01a42b4c230de8b2c7540089cc15b945529a5b`, with super-linter
`4ce20838b8ab83717e78138c5b3a1407148e0918` and no YAML override. Its
[published default
configuration](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml),
blob `2aa49bd1867e24acdea4172191922df6135b69c6`, is saved unmodified
outside source. Its [dependency
pin](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/dependencies/python/yamllint.txt),
blob `7ce0eabce1e3283119086a7ae179f2373fc00e13`, matches installed
yamllint 1.38.0. This is a pinned shared-validator default for local
checks, not this repository's CI configuration. The installed default
also matches upstream commit `cba56bcde1fdd01c1deb3f945e69764c291a6530`,
blob `b082e228469dd5909a6f58dd2466882e16d4ea87`.

For each of the three base blobs and corresponding candidate files, the
exact commands receive the original input bytes through stdin:

```powershell
$shared = "$env:USERPROFILE\.copilot\session-state\73d907e5-c9b5-46c2-ab63-6404c149f36f\files\super-linter-4ce20838-yaml-default.yml"
python -m yamllint --config-file $shared -
python -m yamllint --strict --config-file $shared -
python -m yamllint --strict --config-data 'extends: default' -
```

| Fresh verification | Result |
| --- | --- |
| Pinned shared-validator default, normal and strict | All 3 base and
all 3 candidate files pass in both modes: 12 runs, exit 0, zero
diagnostics. No published rule is weakened. |
| Explicit installed default, strict | All 3 base and all 3 candidate
files pass: 6 runs, exit 0, zero diagnostics. |
| PyYAML 6.0.3 complete contract comparison | All 3 actual-base
contracts match across 28 mappings, 6 sequences, and 122 scalar nodes.
Exactly 10 prose values differ; all 112 other scalar nodes, key/field
order, tags, styles, and comments are preserved. |
| Full input and routing contract | All 7 textarea IDs, types, labels,
and required flags match: 5 required and 2 optional. Form names, titles,
top-level descriptions, labels, and routing match. |
| `git diff --check` | Passed, exit 0. |
| `git diff
0c67251...deb2e80
--check` | Passed, exit 0. |
| `git diff --name-only
0c67251...deb2e80`
| Exactly the three owned forms: `01-bug.yml`, `02-patch.yml`, and
`99-general.yml`, under `.github/ISSUE_TEMPLATE`. |

**Native rendering and links:** `gh api --include --method POST markdown
-H 'Accept: text/html' --input -` sends each parsed introduction to
GitHub with JSON `mode: gfm` and `context: MSXOrg/.github`. All 6
requests, covering 3 baseline and 3 candidate introductions, return HTTP
200. Each renders as one paragraph with complete visible text. The
candidate bug and general introductions each contain one native `<br>`;
patch has none. This is real Markdown rendering, not a simulated form or
an issue-submission test. All 48 scalar string values across the
candidate forms contain zero link targets, and native output contains
zero links or images. Link verification is inapplicable, not a passing
empty scan.

**Standards and scope:** The writing review uses the fixed MSX
Documentation Model, Natural Language, Writing Guide, Markdown,
Documentation, YAML, Testing, and applicable delivery guidance. The
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
official STE overview/FAQ, and locally verified Issue 9 support the
review without a full STE-conformance claim. The native issue-form
format remains intact.

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/ISSUE_TEMPLATE/01-bug.yml` | Direct en-US prompts, preserved
meaning, YAML | Native GitHub issue-form format | Fixed in this PR |
| `.github/ISSUE_TEMPLATE/02-patch.yml` | Direct en-US prompts,
preserved meaning, YAML | Native GitHub issue-form format | Fixed in
this PR |
| `.github/ISSUE_TEMPLATE/99-general.yml` | Direct en-US prompts,
preserved meaning, YAML | Native GitHub issue-form format | Fixed in
this PR |

The feature form, `config.yml`, tests, validation tooling, README,
contribution guidance, PR template, agent instructions, profile,
security, and support files remain unchanged. The repository's fallback
role and central-standards link remain correct. No maintained
phrase/snapshot test, linter, dependency, workflow, label, ruleset,
scheduler, or policy change is added. The original scoped convergence
sweep found #16 and feature Task #14; the
latter is not satisfied by this diff. Only #16 receives a
closing reference.

**Current reviews and protections:** The [current-head Copilot
approval](#21 (review))
remains `APPROVED`. Fully paginated inspection finds zero inline
comments, zero review threads, and no new PR comments. GitHub reports
`APPROVED`, `MERGEABLE`, and `CLEAN`. `gh pr checks` reports no checks;
the exact-head REST endpoint retains one successful historical review
check and zero commit statuses. No hosted repository-validation result
exists; the review check is not one.

Inherited active ruleset `19735160` requires squash-only PRs,
stale-review dismissal, code-owner review, last-push approval, extra
approval for unattributed changes, and thread resolution. No
required-status-check rule is present. The classic protection endpoint's
HTTP 404 does not remove these rules. No `CODEOWNERS` file exists at a
supported location in the actual base. Copilot is the only approving
account and its collaborator-permission response is `none`; native
readiness metadata is not used as proof of an independently eligible
last-push approval or as permission to bypass protection.

**Lifecycle:** The PR is open and non-draft under the later
user-directed lifecycle change. GitHub auto-merge is null. Agent merge
readback is enabled with `merge_pr=false`. The exclusive global merge
slot remains with the root coordinator; no merge is attempted. Missing
hosted CI remains disclosed. Operational exact-head local evidence does
not install CI or waive an actual failing check.

The [fresh issue
evidence](#16 (comment))
records the exact provenance, commands, results, and remaining
authorization boundary. Full diagnostics, configuration bytes,
ordered-tree comparison, and native HTML responses remain in local
session artifacts, not in the repository. There is no source or access
blocker.

</details>

<details>
<summary>Relevant issues (or links)</summary>

<!-- Use fully qualified repository references for closing and related
work. -->

- Resolves #16
- References #12 for separate validation work, not an
installed check or dependency.
- References #15 for the separately owned feature form.

</details>
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.

Focus organization feature intake on consumer needs and expected behavior

2 participants