From 6c387f1dfbcc4522c419ae2abefbed42a64f44c2 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Thu, 4 Jun 2026 21:57:58 -0700 Subject: [PATCH] chore(github): add YAML issue forms and auto-triage workflow Add `.github/ISSUE_TEMPLATE/` with five YAML issue forms (bug, feature, enhancement, adapter, docs) plus a config that disables blank issues and points contributors at Discord #dev and ROADMAP.md. Bug report enforces version, deployment mode, install method, DB mode, adapter context, repro steps, and a mandatory privacy checklist with PII warnings on every paste-style field. Feature and enhancement forms include a subsystem picker so the queue can be filtered by area. Add `.github/workflows/auto-label-issues.yml` to apply `needs-triage` to every new issue (self-healing label creation, SHA-pinned actions/github-script@v9.0.0, no untrusted input interpolated into shell). All template labels also include `needs-triage` so the queue view is consistent without depending on the workflow. Co-Authored-By: Paperclip --- .github/ISSUE_TEMPLATE/adapter_request.yml | 42 +++++ .github/ISSUE_TEMPLATE/bug_report.yml | 174 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/docs_issue.yml | 44 ++++++ .github/ISSUE_TEMPLATE/enhancement.yml | 91 +++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 53 +++++++ .github/workflows/auto-label-issues.yml | 42 +++++ 7 files changed, 454 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/adapter_request.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/docs_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/enhancement.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/workflows/auto-label-issues.yml diff --git a/.github/ISSUE_TEMPLATE/adapter_request.yml b/.github/ISSUE_TEMPLATE/adapter_request.yml new file mode 100644 index 00000000000..b1c3d74681c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/adapter_request.yml @@ -0,0 +1,42 @@ +name: New agent adapter +description: Request or propose support for a new AI agent or model provider +labels: [adapter, needs-triage] +body: + - type: markdown + attributes: + value: | + New agent adapters are welcome without prior discussion. If you plan to implement, prefer extending Paperclip via the [plugin system](https://github.com/paperclipai/paperclip/blob/master/doc/plugins/PLUGIN_SPEC.md) when possible. + - type: input + id: agent + attributes: + label: Agent or provider + description: Name of the agent, model, or CLI tool. + placeholder: e.g. Gemini CLI, LM Studio, Mistral + validations: + required: true + - type: textarea + id: why + attributes: + label: Why this adapter is useful + description: What use cases does this unlock? Who would benefit? + validations: + required: true + - type: textarea + id: how-invoked + attributes: + label: How the agent is invoked + description: CLI command, API endpoint, SDK — whatever is relevant. Link docs if available. + validations: + required: true + - type: checkboxes + id: willing + attributes: + label: Are you willing to implement it? + options: + - label: Yes, I plan to open a PR + - label: No, requesting for someone else to pick up + - type: textarea + id: context + attributes: + label: Additional context + description: Links, examples from existing adapters, configuration quirks, etc. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000000..229344d0c16 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,174 @@ +name: Bug report +description: Something is broken or behaving unexpectedly +labels: [bug, needs-triage] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug. Please fill out the sections below so we can reproduce and triage quickly. + + > **⚠️ Privacy notice:** Several fields below accept logs, config, or transcript output that may contain **personally identifiable information (PII)** — usernames in file paths, API keys, tokens, company names, agent output, or task content. Before pasting: + > 1. Review for sensitive data + > 2. Redact usernames, paths, API keys, tokens (e.g. replace `/Users/yourname/` with `/Users/REDACTED/`) + > 3. For heavy output, consider running it through an anonymizer such as **[presidio-anonymizer](https://microsoft.github.io/presidio/)** (open-source, local-only) or **[scrub](https://github.com/dssg/scrub)** + + - type: checkboxes + id: preflight + attributes: + label: Pre-submission checklist + description: Please confirm each of these before filing. + options: + - label: I have searched existing open and closed issues and this is not a duplicate. + required: true + - label: I am on the latest released version of Paperclip (or can reproduce on `master`). + required: true + - label: I have confirmed the error originates in Paperclip itself — not in my agent adapter, API provider, or local configuration. + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: A clear description of the bug. Be specific about which Paperclip command, endpoint, or UI action was involved. + placeholder: When I do X, Y happens instead of Z. + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should have happened instead. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Numbered steps a maintainer can follow to reproduce the bug. Start from a clean install where possible. + value: | + 1. + 2. + 3. + validations: + required: true + + - type: input + id: paperclip-version + attributes: + label: Paperclip version or commit + description: Output of `paperclipai --version` or the commit SHA you are running. + placeholder: e.g. 0.42.0 or 78dc3625ac + validations: + required: true + + - type: dropdown + id: deployment + attributes: + label: Deployment mode + options: + - Local dev (pnpm dev) + - Docker + - Self-hosted server + - Other + validations: + required: true + + - type: dropdown + id: install_method + attributes: + label: Installation method + options: + - npm / pnpm global install + - Docker + - Built from source (pnpm dev / pnpm build) + - Other + validations: + required: false + + - type: checkboxes + id: adapters + attributes: + label: Agent adapter(s) involved + description: Select all that apply. If unsure, leave unchecked and describe in additional context. + options: + - label: Claude Code + - label: Codex + - label: Cursor + - label: Droid + - label: Hermes + - label: Custom / external plugin adapter + - label: Not adapter-specific (core bug) + + - type: dropdown + id: database + attributes: + label: Database mode + options: + - Embedded PGlite (default — `DATABASE_URL` unset) + - External Postgres + - Not database-related + validations: + required: false + + - type: dropdown + id: access_context + attributes: + label: Access context + description: Whose credentials were being used when the bug occurred? + options: + - Board (human operator) + - Agent (bearer API key via `agent_api_keys`) + - Both + - Unclear / not applicable + validations: + required: false + + - type: input + id: node-version + attributes: + label: Node.js version + description: Output of `node --version`. + placeholder: e.g. v20.18.0 + + - type: input + id: os + attributes: + label: Operating system + placeholder: e.g. macOS 14.5 (Apple Silicon), Ubuntu 22.04 + + - type: textarea + id: logs + attributes: + label: Relevant logs or output + description: | + Paste error messages, stack traces, or API responses. Will be rendered as a code block. + + **⚠️ PII warning:** Server logs often contain file paths with your username (e.g. `/Users/yourname/...`). Redact before pasting. + render: shell + + - type: textarea + id: config + attributes: + label: Relevant config (if applicable) + description: | + If the bug is config-related, paste the relevant snippet. + + **⚠️ PII warning:** Paperclip config may contain API keys, encrypted-secrets paths, company names, or tokens. **Remove all secrets before pasting.** + render: json + + - type: textarea + id: context + attributes: + label: Additional context + description: Screenshots, related issues, or anything else that might help. + + - type: checkboxes + id: pii_confirmed + attributes: + label: Privacy checklist + description: Please confirm you've reviewed your submission for sensitive data. + options: + - label: I have reviewed all pasted output for PII (usernames, file paths, API keys, tokens, company names) and redacted where necessary. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000000..c0c9d902145 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Discord (#dev) + url: https://discord.gg/paperclipai + about: Design discussions, questions, and feature coordination before opening a PR + - name: Roadmap + url: https://github.com/paperclipai/paperclip/blob/master/ROADMAP.md + about: Check the roadmap before requesting a feature diff --git a/.github/ISSUE_TEMPLATE/docs_issue.yml b/.github/ISSUE_TEMPLATE/docs_issue.yml new file mode 100644 index 00000000000..1cdb790c16b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_issue.yml @@ -0,0 +1,44 @@ +name: Documentation issue +description: Report incorrect, missing, or unclear documentation +labels: [documentation, needs-triage] +body: + - type: markdown + attributes: + value: | + Help improve the docs. Point us at what's wrong, missing, or confusing. + + - type: dropdown + id: type + attributes: + label: Issue type + options: + - Incorrect information + - Missing documentation + - Unclear or confusing + - Outdated (no longer matches behavior) + - Typo or formatting + validations: + required: true + + - type: input + id: location + attributes: + label: Where is the issue? + description: File path, URL, or section name. + placeholder: "e.g. README.md#installation, doc/DEVELOPING.md, docs/plugins.md" + validations: + required: true + + - type: textarea + id: description + attributes: + label: What's wrong? + description: Describe the documentation issue. + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested fix + description: If you know what the correct information should be, include it here. diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml new file mode 100644 index 00000000000..79624c4d656 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/enhancement.yml @@ -0,0 +1,91 @@ +name: Enhancement proposal +description: Propose an improvement to an existing Paperclip feature +labels: [enhancement, needs-triage] +body: + - type: markdown + attributes: + value: | + An enhancement improves something that already exists — better output, broader edge-case handling, clearer UX, performance. It does not add new commands, endpoints, or concepts. If you are proposing something new, use the **Feature request** template instead. + + - type: checkboxes + id: preflight + attributes: + label: Pre-submission checklist + options: + - label: I have confirmed this improves existing behavior — it does not add a new command, endpoint, or concept. + required: true + - label: I have searched existing open and closed issues and this has not already been proposed. + required: true + + - type: input + id: what_is_improved + attributes: + label: What existing behavior does this improve? + description: Name the specific command, endpoint, UI view, or behavior being enhanced. + placeholder: "e.g. /api/companies response shape, board task list sorting, adapter startup log output" + validations: + required: true + + - type: dropdown + id: subsystem + attributes: + label: Subsystem affected + options: + - server/ — REST API & orchestration services + - ui/ — React + Vite board UI + - packages/db — Drizzle schema, migrations + - packages/shared — types, constants, validators, API paths + - packages/adapters — agent adapter implementations + - packages/plugins — plugin system + - Cross-cutting (multiple of the above) + - Unsure + validations: + required: true + + - type: textarea + id: current_behavior + attributes: + label: Current behavior + description: Describe exactly how it works today. Include example output or a screenshot if helpful. + placeholder: | + Currently, when I call ..., the response is ... + validations: + required: true + + - type: textarea + id: proposed_behavior + attributes: + label: Proposed behavior + description: Describe exactly how it should work after the enhancement. Include example output. + placeholder: | + After this enhancement, the response would be ... + validations: + required: true + + - type: textarea + id: reason + attributes: + label: Reason and benefit + description: | + Why is the current behavior a problem, and what is the concrete benefit of the proposed behavior? + + Vague answers like "it would be better" or "more user-friendly" are not enough. + validations: + required: true + + - type: textarea + id: breaking_changes + attributes: + label: Breaking changes + description: | + Does this change any behavior, response shape, or output format that users or agents might rely on? + If yes, describe exactly what changes and how backward compatibility is maintained. + Write "None" only if you are certain. + validations: + required: true + + - type: textarea + id: additional_context + attributes: + label: Additional context + description: Screenshots, related issues, or anything else. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000000..650c8443a4e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,53 @@ +name: Feature request +description: Propose a new capability or improvement +labels: [enhancement, needs-triage] +body: + - type: markdown + attributes: + value: | + Feature work on core Paperclip is coordinated against `ROADMAP.md` and Discord `#dev`. Please skim those before filing — see [CONTRIBUTING.md](https://github.com/paperclipai/paperclip/blob/master/CONTRIBUTING.md) for the full guidance. + - type: dropdown + id: subsystem + attributes: + label: Subsystem affected + description: Which part of the codebase would this primarily live in? + options: + - server/ — REST API & orchestration services + - ui/ — React + Vite board UI + - packages/db — Drizzle schema, migrations + - packages/shared — types, constants, validators, API paths + - packages/adapters — agent adapter implementations + - packages/plugins — plugin system + - Cross-cutting (multiple of the above) + - Unsure + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem or motivation + description: What are you trying to do that is currently difficult or impossible? + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed solution + description: Describe the feature you'd like. How should it work? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about and why you ruled them out. + - type: textarea + id: roadmap + attributes: + label: Roadmap alignment + description: Does this relate to anything in `ROADMAP.md`? Link the relevant section if so. + - type: textarea + id: context + attributes: + label: Additional context + description: Mockups, examples from other tools, related issues, etc. diff --git a/.github/workflows/auto-label-issues.yml b/.github/workflows/auto-label-issues.yml new file mode 100644 index 00000000000..9268da30cee --- /dev/null +++ b/.github/workflows/auto-label-issues.yml @@ -0,0 +1,42 @@ +name: Auto-label new issues + +# Security review: this workflow only reads context.issue.number, context.repo.owner, +# and context.repo.repo via actions/github-script. No untrusted user input +# (issue title, body, comments, head_ref, etc.) is interpolated into shell commands. +# No run: steps at all — all logic runs inside github-script's JS sandbox. + +on: + issues: + types: [opened] + +permissions: + issues: write + +jobs: + add-triage-label: + runs-on: ubuntu-latest + timeout-minutes: 2 + steps: + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + // Ensure the label exists before applying it. Self-healing on first run. + try { + await github.rest.issues.createLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + name: 'needs-triage', + color: 'fbca04', + description: 'Newly filed, not yet reviewed by a maintainer', + }); + } catch (e) { + // 422 = label already exists — safe no-op. + if (e.status !== 422) throw e; + } + + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['needs-triage'], + });