From 6750f3d973f4272d8270d2e3615045dd16bca071 Mon Sep 17 00:00:00 2001 From: Matthew Digman Date: Tue, 18 Aug 2026 17:26:01 -0500 Subject: [PATCH] docs: convert issue forms to markdown templates The YAML issue forms rendered as a fixed form with no editable body, which is more rigid than this project needs. Markdown templates prefill the same guidance as an editable body, keeping the chooser entries, title prefixes, and auto-applied labels. Also drops the Questions and Documentation contact links: a contact link navigates away from issue creation, so pointing one at the docs site meant "Documentation" opened the docs rather than a docs issue. Security keeps its link, where redirecting away from a public issue is the intent. Two corrections carried in: the adapter template no longer uses vulture as its example, since vulture already ships an adapter, and the corpus template spells out the SPDX allowlist inline instead of hiding it in a dropdown. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/01_bug_report.md | 61 ++++++++++ .github/ISSUE_TEMPLATE/01_bug_report.yml | 107 ------------------ .github/ISSUE_TEMPLATE/02_adapter_request.md | 52 +++++++++ .github/ISSUE_TEMPLATE/02_adapter_request.yml | 72 ------------ .../ISSUE_TEMPLATE/03_corpus_suggestion.md | 50 ++++++++ .../ISSUE_TEMPLATE/03_corpus_suggestion.yml | 97 ---------------- .github/ISSUE_TEMPLATE/04_feature_request.md | 43 +++++++ .github/ISSUE_TEMPLATE/04_feature_request.yml | 46 -------- .github/ISSUE_TEMPLATE/config.yml | 8 +- 9 files changed, 207 insertions(+), 329 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/01_bug_report.md delete mode 100644 .github/ISSUE_TEMPLATE/01_bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/02_adapter_request.md delete mode 100644 .github/ISSUE_TEMPLATE/02_adapter_request.yml create mode 100644 .github/ISSUE_TEMPLATE/03_corpus_suggestion.md delete mode 100644 .github/ISSUE_TEMPLATE/03_corpus_suggestion.yml create mode 100644 .github/ISSUE_TEMPLATE/04_feature_request.md delete mode 100644 .github/ISSUE_TEMPLATE/04_feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md new file mode 100644 index 0000000..b1de121 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_bug_report.md @@ -0,0 +1,61 @@ +--- +name: Bug report +about: liveness_primer crashed, produced a wrong report, or behaved differently than documented. +title: '[bug] ' +labels: bug +--- + + + +## Environment + +- **liveness_primer version:** +- **Python version:** +- **Operating system:** +- **Detector and revisions:** +- **Corpus projects involved:** + +## Description + + + +## Reproduction + + + +```console +$ +``` + +## Expected behavior + + + +## Actual behavior + + + +```console +``` + +## Report excerpt + + + +## Anything else + + diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.yml b/.github/ISSUE_TEMPLATE/01_bug_report.yml deleted file mode 100644 index ff236fc..0000000 --- a/.github/ISSUE_TEMPLATE/01_bug_report.yml +++ /dev/null @@ -1,107 +0,0 @@ -name: Bug report -description: liveness_primer crashed, produced a wrong report, or behaved differently than documented. -title: '[bug] ' -labels: ['bug'] -body: - - type: markdown - attributes: - value: | - Thanks for the report. A bug in liveness_primer is typically - reproducible from a single command plus the two detector refs, so the - fields below are what a maintainer needs to see it happen. - - Security issues should go through - [SECURITY.md](https://github.com/mcdigman/liveness_primer/blob/main/SECURITY.md). - - - type: input - id: version - attributes: - label: liveness_primer version - description: Output of `liveness-primer --version` (it includes the schema version) - placeholder: 'liveness-primer 0.1.0 (schema 2.2.0)' - validations: - required: false - - - type: input - id: python-version - attributes: - label: Python version - description: Output of `python --version`. - placeholder: 'Python 3.12.8' - validations: - required: false - - - type: input - id: platform - attributes: - label: Operating system - placeholder: 'macOS 14.5 (arm64) / Ubuntu 24.04 (x86_64) / ubuntu-latest GitHub runner' - validations: - required: false - - - type: input - id: detector - attributes: - label: Detector and revisions - description: The `--tool` name, repo and the versions or full pinned hashes of the 2 commits that reproduce the bug, if applicable - placeholder: 'skylos https://github.com/duriantaco/skylos a27bd86223a948fe292677e71bd84e19c1ab24fa e25b12eba4a2f80ad031b388ec81049d46be8f90' - validations: - required: false - - - type: input - id: targets - attributes: - label: Corpus projects involved - description: The `-k` selections, `--all`, or the `--project` URL. If only some projects fail, say which. - placeholder: '-k pluggy (also fails on attrs; passes on click)' - validations: - required: false - - - type: textarea - id: description - attributes: - label: Description of the Bug - validations: - required: true - - - type: textarea - id: reproducer - attributes: - label: Reproduction - description: If possible, minimal code example that reproduces the bug, and the exact command needed to run it. - validations: - required: false - - - type: textarea - id: expected - attributes: - label: Expected behavior - description: What you expected, and where that expectation comes from (docs, `--help`, a prior version). - validations: - required: false - - - type: textarea - id: actual - attributes: - label: Actual behavior - description: What happened instead. Paste the terminal output or traceback — the whole thing, not just the last line. Redact paths or tokens if you need to. - render: shell - validations: - required: false - - - type: textarea - id: report - attributes: - label: Report excerpt - description: | - If the bug is about report content rather than a crash, attach the JSON report (`--json-out report.json`) or paste the relevant entry. Drag-and-drop works for files. - validations: - required: false - - - type: textarea - id: context - attributes: - label: Anything else - description: Additional context, screenshots, link to failing CI run, etc. - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/02_adapter_request.md b/.github/ISSUE_TEMPLATE/02_adapter_request.md new file mode 100644 index 0000000..6d3dee3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02_adapter_request.md @@ -0,0 +1,52 @@ +--- +name: Detector adapter request +about: Ask for a new detector or linter to be supported by a liveness_primer adapter. +title: '[adapter] ' +labels: 'adapter, enhancement' +--- + + + +- **Detector name:** +- **Source repository:** + +## What does it detect, and why compare revisions of it? + + + +## Output format + + + +## Revisions worth comparing first + + + +## Corpus applicability + + diff --git a/.github/ISSUE_TEMPLATE/02_adapter_request.yml b/.github/ISSUE_TEMPLATE/02_adapter_request.yml deleted file mode 100644 index ca693c4..0000000 --- a/.github/ISSUE_TEMPLATE/02_adapter_request.yml +++ /dev/null @@ -1,72 +0,0 @@ -name: Detector adapter request -description: Ask for a new detector or linter to be supported by a liveness_primer adapter. -title: '[adapter] ' -labels: ['adapter', 'enhancement'] -body: - - type: markdown - attributes: - value: | - An adapter teaches `liveness_primer` to build one - detector at two revisions, invoke it, and normalize its output into - the shared finding model. The ones that work well are deterministic, - installable from a git ref, and pointable at a directory. - - The answers below decide whether an adapter is feasible at all, so a - partly filled form is fine — say "not sure" rather than guessing. - - - type: input - id: detector-name - attributes: - label: Detector name - placeholder: 'vulture' - validations: - required: true - - - type: input - id: repo - attributes: - label: Source repository - description: Adapters build from a git ref, so a public repository is required. - placeholder: 'https://github.com/owner/project' - validations: - required: true - - - type: textarea - id: what-it-finds - attributes: - label: What does it detect, and why compare revisions of it? - description: What kinds of findings it reports, and what a blast-radius comparison would tell you that its own test suite does not. - validations: - required: false - - - type: dropdown - id: output-format - attributes: - label: Output format - description: Machine-readable output is much easier to normalize; text output is supported but needs a stable, parseable shape. - options: - - JSON (documented and stable) - - JSON (present but undocumented) - - Text (stable line format) - - Text (free-form) - - SARIF - - Other / not sure - validations: - required: false - - - type: input - id: refs - attributes: - label: Revisions worth comparing first - description: Two refs a maintainer can use to smoke-test the adapter. - placeholder: 'v2.3.0 vs v2.4.0' - validations: - required: false - - - type: textarea - id: targets - attributes: - label: Corpus applicability - description: Does it analyze the same source directories the existing corpus entries declare, or does it need different targets (installed packages, tests, a whole checkout)? Rough per-project runtime is useful too. - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/03_corpus_suggestion.md b/.github/ISSUE_TEMPLATE/03_corpus_suggestion.md new file mode 100644 index 0000000..4f7d765 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03_corpus_suggestion.md @@ -0,0 +1,50 @@ +--- +name: Corpus suggestion +about: Propose a project for the pinned corpus, or a change to an existing entry. +title: '[corpus] ' +labels: corpus +--- + + + +## What is this? + + + +- Add a new project +- Re-pin an existing project +- Additional pin for an existing project +- Change targets or cost for an existing project +- Remove a project + +## Entry + +- **Project name:** +- **Repository URL:** +- **License (SPDX):** +- **Proposed pin:** + +## What does it cover that the current corpus does not? + +## Size and maintenance + + + +## Anything else + + diff --git a/.github/ISSUE_TEMPLATE/03_corpus_suggestion.yml b/.github/ISSUE_TEMPLATE/03_corpus_suggestion.yml deleted file mode 100644 index fe13f0e..0000000 --- a/.github/ISSUE_TEMPLATE/03_corpus_suggestion.yml +++ /dev/null @@ -1,97 +0,0 @@ -name: Corpus suggestion -description: Propose a project for the pinned corpus, or a change to an existing entry. -title: '[corpus] ' -labels: ['corpus'] -body: - - type: markdown - attributes: - value: | - Corpus entries are the targets every comparison runs - against, so each one must be GitHub-hosted, permissively licensed, - moderate in size, and pinned to a full commit SHA - — both detector revisions have to analyze byte-identical checkouts. - - The gate on - [liveness_primer/data/corpus.yaml](https://github.com/mcdigman/liveness_primer/blob/main/liveness_primer/data/corpus.yaml) - runs `corpus validate` and a GitHub license check on every PR, so an - entry that fails these fields will fail CI too. - - - type: dropdown - id: kind - attributes: - label: What is this? - options: - - Add a new project - - Re-pin an existing project - - Additional pin for an existing project - - Change targets or cost for an existing project - - Remove a project - validations: - required: true - - - type: input - id: name - attributes: - label: Project name - description: The corpus key. Short, lowercase, unique. - placeholder: 'pluggy' - validations: - required: true - - - type: input - id: repo - attributes: - label: Repository URL - description: Must be GitHub-hosted. - placeholder: 'https://github.com/pytest-dev/pluggy' - validations: - required: true - - - type: dropdown - id: license - attributes: - label: License (SPDX) - description: Anything outside the allowlist needs human review. - options: - - MIT - - Apache-2.0 - - BSD-2-Clause - - BSD-3-Clause - - ISC - - PSF-2.0 - - Other (explain below) - validations: - required: false - - - type: input - id: pin - attributes: - label: Proposed pin - description: A full 40-character commit SHA, not a tag or branch. - placeholder: 'f06ceaafbe5bdbdafad8a0c01a2daabb89386a42' - validations: - required: false - - - type: textarea - id: coverage - attributes: - label: What does it cover that the current corpus does not? - validations: - required: false - - - type: textarea - id: health - attributes: - label: Size and maintenance - description: Rough source size, recent commit or release activity, and how long a detector takes on it. Very large projects may be too expensive for per-PR tool runs. - placeholder: 'about 3k lines under src/, released last month, ~5s under skylos' - validations: - required: false - - - type: textarea - id: context - attributes: - label: Anything else - description: For a re-pin, why now. For an additional pin, why it adds additional value. For a removal, what changed. For an unusual license, the reasoning. - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/04_feature_request.md b/.github/ISSUE_TEMPLATE/04_feature_request.md new file mode 100644 index 0000000..17e1976 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/04_feature_request.md @@ -0,0 +1,43 @@ +--- +name: Feature request +about: Propose new behavior, a CLI or report change, or an improvement to existing output. +title: '[feature] ' +labels: enhancement +--- + + + +## Problem + + + +## Proposed behavior + + + +## Alternatives considered + + + +## Compatibility + + diff --git a/.github/ISSUE_TEMPLATE/04_feature_request.yml b/.github/ISSUE_TEMPLATE/04_feature_request.yml deleted file mode 100644 index 42802d3..0000000 --- a/.github/ISSUE_TEMPLATE/04_feature_request.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Feature request -description: Propose new behavior, a CLI or report change, or an improvement to existing output. -title: '[feature] ' -labels: ['enhancement'] -body: - - type: markdown - attributes: - value: | - Please open the issue before writing the code — this project has - strict gates and a deliberately narrow scope, and agreeing on the - shape first saves a review round. - - New detector support belongs in the **Detector adapter request** form; - new target projects belong in **Corpus suggestion**. - - - type: textarea - id: problem - attributes: - label: Problem - description: What are you trying to do, and where does the current behavior get in the way? Describe the situation, not the solution. - validations: - required: true - - - type: textarea - id: proposal - attributes: - label: Proposed behavior - description: What `liveness_primer` should do instead. Concrete beats abstract — a sample command, a sample line of output, a sample report field. - validations: - required: false - - - type: textarea - id: alternatives - attributes: - label: Alternatives considered - description: Existing flags, post-processing the JSON report, or doing it outside the tool — and why those fall short. - validations: - required: false - - - type: textarea - id: compatibility - attributes: - label: Compatibility - description: Would this change existing output, defaults, or exit codes for someone already using the tool? If so, say how it could land without breaking them. - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 9df9997..2ea7a4c 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,13 +1,7 @@ -# Issue-form chooser configuration. +# Issue template chooser configuration. blank_issues_enabled: true contact_links: - - name: Questions and help - url: https://github.com/mcdigman/liveness_primer/discussions - about: Ask usage questions and get help from the community. - name: Security vulnerability url: https://github.com/mcdigman/liveness_primer/blob/main/SECURITY.md about: Do not open a public issue. Follow the private disclosure process in SECURITY.md. - - name: Documentation - url: https://liveness-primer.readthedocs.io/ - about: Usage, CI integration, and the report explorer.