Just an FYI - Changes to PR Submissions/Enhancemets/Feature Requests

[trek-e]

CI improvements and contribution guardrails — what's changing and why

With Anthropic's recent changes to Claude and Claude Code, we're seeing a meaningful uptick in people discovering and using GSD. That's great — and it also means the contribution volume is going to grow, which means we need the project's quality guardrails to grow with it.

This post is a heads-up about some CI, testing, and contribution process changes that landed recently, and why we made them. Nothing here changes how you use GSD day-to-day, but if you're a contributor (or thinking about becoming one), it's worth reading.

---

What changed: CI and testing

We dropped the Windows CI runner from the main test matrix and replaced it with a dedicated static analysis test (hardcoded-paths.test.cjs) that catches the same class of bugs — hardcoded C:\ paths, /home/username/ and /Users/username/ absolute paths, and /tmp/ — more reliably and without the slow, expensive Windows runner. The tests that were running on Windows were doing static file analysis that produced identical results on Linux. The new test is explicit about what it's looking for and runs in under 100ms on every PR.

The macOS smoke runner was also bumped to Node 24 (our declared standard) rather than Node 22, so it's actually validating the version most of you are running.

We bumped the declared engines.node minimum from >=20.0.0 to >=22.0.0, since Node 20 went EOL this month.

On the testing side, we also backported standards from gsd-2: t.after() is now a supported cleanup pattern for per-test teardown, multi-line fixture data should use array join() instead of template literals (whitespace contamination in template literals causes subtle regex failures that are hard to diagnose), and Node 24 is now the explicit primary CI target with Node 22 as the backward-compat floor. Bug fixes now require a regression test — one that demonstrates the original failure before the fix and passes after. Green CI on a fix without a regression test is not sufficient for merge.

---

What changed: contribution process

This is the bigger change, and the more important one to understand if you're planning to contribute.

CONTRIBUTING.md now defines three explicit contribution types — Fix, Enhancement, and Feature — each with a different process and a different bar for acceptance.

A fix corrects broken behavior. Open a bug report, wait for it to be confirmed, fix it, write a regression test, open a PR. That process is largely unchanged from before.

An enhancement improves something that already exists — better output, expanded edge-case handling, cleaner UX. Enhancements now require a written proposal in an issue before any code is written. The issue needs to describe the current behavior, the proposed behavior, why the current behavior is actually a problem (not just "it would be nicer"), the concrete benefit, and the scope of changes. A maintainer labels the issue approved-enhancement before you touch a line of code. PRs for enhancements without that label are closed without review.

A feature adds something new — a new command, workflow, concept, or integration. Features have the highest bar because every feature is code we maintain forever. The feature request issue template now requires a complete spec: the solo-developer problem being solved, exactly what is being added, every file and system that would be touched, user stories, acceptance criteria, a maintenance burden assessment, and alternatives considered. A maintainer labels the issue approved-feature before you write any code. Incomplete specs are closed, not revised by maintainers.

We also added typed PR templates — separate templates for Fix, Enhancement, and Feature — and converted the default PR template into a routing page. Each typed template has a hard gate at the top: if the linked issue doesn't carry the correct approval label, the checklist makes it explicit that the PR will be closed. This isn't meant to be hostile. It's meant to be clear, so contributors know exactly what's required before they invest time.

---

Why now

The honest reason: we've been on the receiving end of a pattern that most small open source projects know well. A contributor discovers GSD, has an idea, writes the code, opens a PR, and is surprised and frustrated when it gets closed because the direction was never agreed on. That's a bad experience for the contributor and a time sink for maintainers. The new process is designed to catch that friction at the issue stage — before anyone writes code — rather than at the PR stage after they already have.

For fixes, nothing materially changes. For enhancements and features, the new process asks for upfront documentation that a maintainer reviews. If the answer is yes, you get a clear green light before you start. If the answer is no, you find out before you've invested hours building something.

The goal isn't to slow things down. It's to make sure that when we say yes, we mean it, and when we say no, we say it early.

---

This is a work in progress

The CI setup, the test coverage, and the contribution process are all still evolving. If you spot a gap — a category of bug the tests don't catch, a step in the contribution process that's unclear, a template question that's ambiguous — raise it in Discussions. That's exactly the kind of feedback that improves things.

Thanks for using GSD, and especially to those of you who've been filing issues with clean reproductions and well-scoped PRs. It makes a real difference.