Merge pull request #20 from pkgdiff-dev/gsd/quick-261027-contributing-flow

docs(contributing): issue-first flow with linked PRs and issue templates

Author: fleizean

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: A package whose release notes are wrong or missing, or anything else that misbehaves
+title: 'bug: '
+labels: bug
+---
+
+<!-- Security problems do NOT go here — use SECURITY.md. -->
+
+## What happened
+
+<!-- What you saw, and what you expected instead. -->
+
+## Where
+
+- Registry: <!-- nuget / npm / pypi / pub.dev / maven / packagist -->
+- Package:
+- Versions compared: <!-- from -> to -->
+- URL (if any):
+
+## Steps to reproduce
+
+1.
+
+## Notes
+
+<!-- Logs, screenshots, anything else. A pull request that fixes this should link it with "Closes #". -->

.github/ISSUE_TEMPLATE/chore.md

@@ -0,0 +1,20 @@
+---
+name: Chore
+about: Maintenance, tooling, CI, dependencies, docs or process — no user-facing behaviour change
+title: 'chore: '
+labels: chore
+---
+
+## What
+
+<!-- The maintenance task: what changes and where. -->
+
+## Why
+
+<!-- Why it is worth doing now. -->
+
+## Done when
+
+- [ ]
+
+<!-- A pull request for this chore links back with "Closes #". -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/pkgdiff-dev/pkgdiff/security/policy
+    about: Report a security problem privately through SECURITY.md — never a public issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: A new capability or a larger change — agree the approach here before any code
+title: 'feat: '
+labels: enhancement
+---
+
+## Problem
+
+<!-- What is missing or painful today, and for whom. -->
+
+## Proposed approach
+
+<!-- How you would solve it. For a larger change, enough that we can agree on the approach before
+     a pull request is opened. -->
+
+## Alternatives considered
+
+<!-- Or "None". -->
+
+## Scope / out of scope
+
+<!-- What this does and does not cover. A pull request implementing it links back with "Closes #". -->

.github/pull_request_template.md

@@ -4,7 +4,10 @@
 
 ## Why
 
-<!-- The problem it solves. Link the issue (Fixes #123) or name a package and versions that show it. -->
+Closes #
+
+<!-- Replace the number above with the issue this pull request closes. Every pull request links an
+     issue; if one does not exist yet, open it first. -->
 
 ## Changes
 
@@ -16,6 +19,7 @@
 
 ## Checklist
 
+- [ ] This pull request is linked to an issue (`Closes #NNN` above)
 - [ ] The pull request targets `develop` and is about one thing
 - [ ] Commit messages follow Conventional Commits (`feat(scope): ...`, `fix(scope): ...`)
 - [ ] CI is green (backend tests, frontend build and tests, dependency gate)

CONTRIBUTING.md

@@ -5,9 +5,12 @@ and pull requests are all welcome.
 
 ## Before you start
 
-- For a bug, open an issue with the registry, the package, the two versions and what you expected.
-- For a larger change, open an issue first so we can agree on the approach.
-- Security problems go through [SECURITY.md](SECURITY.md), not through an issue.
+Every change starts with an issue. Open one first — a bug, a registry quirk, a feature or a chore —
+using the matching issue template, so the work has a tracked rationale before any code is written.
+
+- For a bug, include the registry, the package, the two versions and what you expected.
+- For a feature or a larger change, describe the approach in the issue so we can agree on it first.
+- Security problems go through [SECURITY.md](SECURITY.md), never a public issue.
 
 ## Setting up
 
@@ -16,7 +19,13 @@ a PostgreSQL and Redis you can reach on `localhost`.
 
 ## Branches and pull requests
 
-- Branch from `develop` and open the pull request into `develop`. `master` only receives releases.
+We work issue-first, with the pull request opened alongside the issue rather than at the end:
+
+- Once an issue exists, branch from `develop` and open the pull request into `develop` early — a
+  draft is fine — so the work is visible while it is still in progress. `master` only receives
+  releases.
+- Link the pull request to its issue with a closing keyword (`Closes #123`) so merging the pull
+  request closes the issue. A pull request without a linked issue will be asked to add one.
 - Keep a pull request about one thing and fill in the pull request template, in English. CI
   (backend tests, frontend build and tests, dependency gate) must be green.
 - Commit messages follow Conventional Commits: `feat(scope): ...`, `fix(scope): ...`, `docs: ...`.