From f3bc1ef0839cc900b33f64ff28b47eb75c77a465 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 2 Jul 2026 11:35:32 +0000 Subject: [PATCH] docs: add CONTRIBUTING.md and PR template to prevent duplicate PRs The repo has repeatedly ended up with multiple open PRs independently implementing the same fix (see #34: 27 open PRs, ~9 duplicate or already superseded by main). Add a CONTRIBUTING.md that requires checking open issues/PRs before starting work, and a PR template with a pre-flight duplicate-check checklist item, to address the root cause identified in #34's suggested fix. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01RSt4rSozqQYR1sRfyvdEcr --- .github/pull_request_template.md | 23 +++++++++++++++++++ CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++ README.md | 6 +++++ 3 files changed, 67 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d0d947d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +## Summary + + + +## Pre-flight duplicate check + + + +- [ ] I searched open issues and open PRs for changes to the same + file(s)/endpoint(s) and did not find an existing one already + covering this change (or I linked the overlapping issue/PR below). + +## Related issues/PRs + + + +## Testing + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cd2f0ed --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,38 @@ +# Contributing + +## Before you start: check for existing work + +This repo has repeatedly ended up with multiple open PRs independently +implementing the same fix against the same file (see +[#34](https://github.com/HailBytes/hailbytes-api-docs/issues/34) for a +concrete example: 27 open PRs, ~9 of them duplicates or already superseded +by `main`). Duplicate work costs reviewer time and produces PRs that +conflict with each other the moment one of them merges. + +Before opening an issue or PR — especially anything touching +`asm/openapi.yaml`, `sat/openapi.yaml`, or `docs/index.html` — check +whether the same change is already in flight: + +1. **Search open issues**: `gh issue list --repo HailBytes/hailbytes-api-docs --state open` +2. **Search open PRs**: `gh pr list --repo HailBytes/hailbytes-api-docs --state open` +3. If an open issue or PR already covers the change you're about to make, + don't start a new one. Either contribute to the existing PR, or comment + on the issue instead. +4. If you find truly duplicate/overlapping open PRs while doing this, + flag it (comment linking the duplicates) rather than adding another one + to the pile. + +## Making a change + +1. Create a branch from `main`. +2. Keep the change scoped to what you're actually fixing — avoid bundling + unrelated cleanups into the same PR, since that makes duplicate + detection and review harder for everyone else. +3. If you're touching `asm/openapi.yaml` or `sat/openapi.yaml`, run + Spectral locally before pushing: + ```bash + npx @stoplight/spectral-cli@6.16.0 lint asm/openapi.yaml --ruleset .spectral.yaml --fail-severity error + npx @stoplight/spectral-cli@6.16.0 lint sat/openapi.yaml --ruleset .spectral.yaml --fail-severity error + ``` +4. Open a PR against `main`. The PR template includes a checklist item + confirming you did the duplicate check above. diff --git a/README.md b/README.md index 5feb8bc..bb54e48 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,12 @@ HailBytes supports MSSP deployments with tenant isolation, delegated API keys, a --- +## Contributing + +Before opening an issue or PR, please check [CONTRIBUTING.md](CONTRIBUTING.md) — +in particular, search existing open issues/PRs first to avoid duplicating +work already in flight. + ## Support - 📧 [support@hailbytes.com](mailto:support@hailbytes.com)