From 8b997e5ec87af378c05e9d95c4594a398120e73b Mon Sep 17 00:00:00 2001 From: Vyncint Ng Date: Tue, 22 Sep 2026 13:01:22 +0700 Subject: [PATCH] chore: add issue forms, a PR template and CODEOWNERS `.github/` held scripts/ and workflows/ and nothing else, and the ecosystem drift log has carried this as a deferred item since 2026-09-07. The forms matter more here than they would for a library. A result depends on the GPU, the driver, the CUDA version, the capability, the cuda-oxide commit, the nightly, and which of the three backends produced the number -- docs/LIMITATIONS.md has a whole section on that -- so a free-text "the tuner picked a slow configuration" is unactionable, and the same report with its provenance block is a bug. Three forms: a wrong convergence verdict in either direction, which is the report that matters most since refusing a fast configuration IS the product; a measurement that disagrees with what you see; and the known hole where a gate-clean candidate still fails the real compile. Blank issues off. A finding wrong about the kernel rather than the launch shape is pointed at reconverge, which this project ships and does not reimplement. Signed-off-by: Vyncint Ng --- .github/CODEOWNERS | 2 + .github/ISSUE_TEMPLATE/build_failure.yml | 43 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 9 +++ .github/ISSUE_TEMPLATE/measurement.yml | 48 ++++++++++++++++ .github/ISSUE_TEMPLATE/wrong_verdict.yml | 70 ++++++++++++++++++++++++ .github/pull_request_template.md | 13 +++++ CHANGELOG.md | 20 +++++++ CONTRIBUTING.md | 17 ++++++ 8 files changed, 222 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/build_failure.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/measurement.yml create mode 100644 .github/ISSUE_TEMPLATE/wrong_verdict.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..0fc8cbf --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Default owners for everything in the repository. +* @vyncint diff --git a/.github/ISSUE_TEMPLATE/build_failure.yml b/.github/ISSUE_TEMPLATE/build_failure.yml new file mode 100644 index 0000000..cbff6c6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/build_failure.yml @@ -0,0 +1,43 @@ +name: An admitted candidate failed to build +description: >- + The gate passed a configuration and `cuda-oxide` then failed to compile + it. This is a known hole with a known cause; reports still help, because + each one names another codegen-time const the gate does not evaluate. +labels: ["bug"] +body: + - type: markdown + attributes: + value: >- + `docs/LIMITATIONS.md` ("cuda-oxide is alpha") records why this + happens: `cargo check` under the reconverge driver does not evaluate + all codegen-time consts, so a gate-clean candidate can still fail the + real compile — an invalid `#[unroll]` factor is the case that was + found first. + - type: input + id: config + attributes: + label: The configuration + description: "As the report prints it, e.g. `block_x=64 tile=128`." + validations: + required: true + - type: textarea + id: error + attributes: + label: The compiler error + render: text + validations: + required: true + - type: textarea + id: kernel + attributes: + label: The kernel and its `kernel.toml` + render: rust + validations: + required: true + - type: input + id: pin + attributes: + label: cuda-oxide pin + description: "`scripts/check-pins.sh` lists every site; rust-toolchain.toml names the set." + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..db47b4f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,9 @@ +blank_issues_enabled: false +contact_links: + - name: A wrong verdict from the convergence analyzer itself + url: https://github.com/vyncint/reconverge/issues/new?template=false_positive.yml + about: >- + launchbound ships reconverge as a component and does not reimplement it. + If the finding is wrong about the kernel rather than about the launch + shape, it belongs upstream — zero false positives at default confidence + is a release requirement there. diff --git a/.github/ISSUE_TEMPLATE/measurement.yml b/.github/ISSUE_TEMPLATE/measurement.yml new file mode 100644 index 0000000..59b6e14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/measurement.yml @@ -0,0 +1,48 @@ +name: A measurement looks wrong +description: >- + A timing, a ranking, or a statistic does not match what you observe — + including the model's estimate disagreeing with silicon. +labels: ["bug"] +body: + - type: markdown + attributes: + value: >- + Before filing: a result is valid only for the GPU, driver and + compiler in its provenance, and `sm_75` and `sm_86` do not transfer + (`docs/LIMITATIONS.md`, "Results do not port"). Two configurations + whose 95% intervals overlap are reported indistinguishable and are + deliberately not ranked. + - type: dropdown + id: backend + attributes: + label: Backend + options: + - cuda (measured on NVIDIA silicon) + - metal (measured on Apple Silicon — no convergence gate on this path) + - model (estimated, not measured) + validations: + required: true + - type: textarea + id: observed + attributes: + label: What you saw, and what you expected + validations: + required: true + - type: textarea + id: results + attributes: + label: The run directory + description: >- + `launchbound report --json`, or the `results.json` itself. It + carries the device name, the driver version, the warmup and repeat + counts and every timing sample, which is most of what this needs. + render: json + validations: + required: true + - type: textarea + id: provenance + attributes: + label: Provenance + description: "`launchbound --version`, the cuda-oxide pin, the nightly, the GPU, the driver and CUDA versions." + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/wrong_verdict.yml b/.github/ISSUE_TEMPLATE/wrong_verdict.yml new file mode 100644 index 0000000..1a5647b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/wrong_verdict.yml @@ -0,0 +1,70 @@ +name: The gate admitted or refused the wrong configuration +description: >- + A configuration launchbound admitted is convergence-unsafe, or one it + refused is safe. This is the report that matters most — refusing a fast + configuration is the product, and getting that wrong in either direction + is the product failing. +labels: ["bug"] +body: + - type: markdown + attributes: + value: >- + If the analyzer is wrong about the *kernel* rather than about the + *launch shape*, it belongs in + [reconverge](https://github.com/vyncint/reconverge/issues) — this + project ships it as a component and does not reimplement it. + `docs/SAFETY.md` has the decision rule this form is about. + - type: textarea + id: kernel + attributes: + label: The kernel + description: >- + Minimal `#[kernel]` source, plus the `kernel.toml` that declares its + space. A corpus kernel is fine — name it instead. + render: rust + validations: + required: true + - type: input + id: config + attributes: + label: The configuration + description: "As the report prints it, e.g. `block_x=64 tile=128`." + validations: + required: true + - type: dropdown + id: direction + attributes: + label: Which way is it wrong? + options: + - Admitted, and it is unsafe (a false negative — the worst case) + - Refused, and it is safe (a false positive) + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Why you believe that + description: >- + A hang on hardware, a `compute-sanitizer synccheck` report, a lane + argument, or the `cargo reconverge check --strict` output for the + shape. Anything is better than nothing; a hang with a driver version + is best. + validations: + required: true + - type: input + id: cc + attributes: + label: "`--cc`" + description: "The capability you ran at. A verdict at one does not transfer to another (docs/LIMITATIONS.md)." + validations: + required: true + - type: textarea + id: provenance + attributes: + label: Provenance + description: >- + `launchbound --version`, the cuda-oxide pin, the nightly, and — if a + measurement is involved — the GPU, driver and CUDA versions. The + report directory's `results.json` carries most of this. + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..12aa06f --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,13 @@ +## Summary + + + +## Checklist + +- [ ] Title is a scoped Conventional Commit (e.g. `bench: …`), imperative, ≤ 72 chars +- [ ] Every commit is signed off (`git commit -s`; the DCO trailer matches the author) +- [ ] No AI attribution anywhere (trailers, message bodies, identities) +- [ ] Tests added or updated, and the new test was watched to fail once +- [ ] `just ci` is green locally +- [ ] Does this move a measured number? If so the CHANGELOG entry is marked `bench:` and names the hardware +- [ ] Does this touch the lockstep pin set (nightly / cuda-oxide / reconverge)? If so it is its own commit and `just pins` passes diff --git a/CHANGELOG.md b/CHANGELOG.md index 17ff7a6..a4b2f07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,26 @@ change measured timings are marked `bench:`. ## [Unreleased] +### Added + +- **Issue forms, a pull-request template and `CODEOWNERS`.** `.github/` held + `scripts/` and `workflows/` and nothing else. + + The forms matter more here than they would for a library, because of what a + report has to contain before anyone can act on it: a result depends on the + GPU, the driver, the CUDA version, the compute capability, the cuda-oxide + commit, the nightly and which of the three backends produced it, and + `docs/LIMITATIONS.md` has a section on exactly that. "The tuner picked a + slow configuration" is unactionable; the same report with its provenance + block is a bug. + + Three of them — a wrong convergence verdict in either direction, a + measurement that disagrees with what you observe, and the known hole where + a gate-clean candidate still fails the real compile. Blank issues are off, + and a finding that is wrong about the kernel rather than the launch shape + is pointed at reconverge, which this project ships as a component and does + not reimplement. + ### Fixed - **`launchbound-runner` accepted a malformed `--budget-secs` in silence, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0b17c3..b94c921 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,23 @@ Thanks for your interest. Issues and small PRs are welcome; large features are better discussed first. +There are three issue forms, and which one you pick matters because a result +here depends on more than the code — the GPU, the driver, the CUDA version, +the compute capability, the cuda-oxide commit, the nightly, and which of the +three backends produced the number (`docs/LIMITATIONS.md`, "Results do not +port"). The forms ask for that provenance so a report is actionable rather +than a starting point for questions: + +| form | for | +|---|---| +| **The gate admitted or refused the wrong configuration** | a convergence verdict that is wrong in either direction — the report that matters most, since refusing a fast configuration *is* the product | +| **A measurement looks wrong** | a timing, a ranking or a statistic that disagrees with what you observe, including the model's estimate against silicon | +| **An admitted candidate failed to build** | the known hole where a gate-clean configuration still fails the real compile | + +A finding that is wrong about the *kernel* rather than the *launch shape* +belongs in [reconverge](https://github.com/vyncint/reconverge/issues): this +project ships it as a component and does not reimplement it. + > **These four projects share one contributor pattern** — the same commit > rules, the same DCO, the same AI policy, the same CI and release shape: > [termlens](https://github.com/vyncint/termlens),