From a4fa0eaf5ea62b3289b45fe52218ccdce6760891 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 5 Jun 2026 22:27:12 -0700 Subject: [PATCH] chore(github): expand issue forms (#7628) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies, and `github.com/paperclipai/paperclip` is the public intake for bugs and feature work > - PR #7575 (just merged) shipped a first cut of `.github/ISSUE_TEMPLATE/`: bug / feature / adapter forms plus a chooser config that disables blank issues — enough to stop greeting filers with an empty textarea > - Reviewing [PR #4189](https://github.com/paperclipai/paperclip/pull/4189) surfaced additional, complementary items worth landing now rather than later: PII handling (logs and config paste fields routinely contain agent transcripts, encrypted-secrets paths, and tokens), richer environment capture for bugs (install method, adapters, DB mode, access context), and a subsystem picker on feature/enhancement so the queue can be filtered by area > - Items 7–10 from #4189 (CONTRIBUTING.md change, AGENTS.md §11, `require-issue-link.yml`, GitHub Discussions contact link) are intentionally deferred — each is its own decision and belongs in a separate, focused PR > - The auto-label workflow that earlier revisions of this branch included was dropped per reviewer feedback — labeling on issue open is a separate concern from the template content and should land (if at all) in its own PR > - This pull request extends the merged templates with PII warnings + a mandatory privacy checkbox on `bug_report.yml`, additional optional env fields, a required subsystem dropdown on `feature_request.yml`, and two net-new templates (`enhancement.yml`, `docs_issue.yml`) > - The benefit is that newly filed issues land with enough environment context and subsystem hint to triage on first read, and paste-field PII is gated by an explicit reviewer-readable checkbox ## Linked Issues or Issue Description Refs #7575 PAPA-521 (follow-up). This is the second half of the issue-templates work — PR #7575 shipped the baseline, this PR adopts items 1, 2, 3, 4, and 6 from PR #4189 on top. Item 5 (auto-label workflow) was dropped per reviewer feedback. ## What Changed - `bug_report.yml` — added PII privacy notice with redaction guidance and anonymizer links; pre-submission preflight checkboxes; optional fields for install method, adapter checkbox list (Claude Code / Codex / Cursor / Droid / Hermes / external plugin / core), database mode (PGlite / external Postgres), and access context (board / agent); inline PII warnings on the logs and config paste fields; mandatory privacy checklist at submission time - `feature_request.yml` — added a required subsystem dropdown (`server/` · `ui/` · `packages/db` · `packages/shared` · `packages/adapters` · `packages/plugins` · cross-cutting · unsure) - `enhancement.yml` — new template for improvements to existing behaviour, with current-vs-proposed-behaviour fields and a required breaking-changes field - `docs_issue.yml` — new lightweight doc-issue form (type / location / description / suggestion) No workflow changes in this PR. ## Verification - All 4 changed YAML files round-trip through `js-yaml` cleanly - Diff vs. master: 4 files changed, +254/-3 (`.github/ISSUE_TEMPLATE/` only) - Post-merge reviewer steps: 1. Visit `github.com/paperclipai/paperclip/issues/new/choose` — expect five template cards (bug, feature, enhancement, adapter, docs) and the existing Discord/Roadmap contact links; no "Open a blank issue" option 2. Open each template in turn — required fields should block submission when empty (in particular: privacy checklist on the bug form, subsystem dropdown on feature/enhancement, breaking-changes field on enhancement) ## Risks - Low risk overall. Files are `.github/ISSUE_TEMPLATE/` config only — no runtime effect on the server, UI, CLI, or any package, and no workflows touched - If a YAML form has a schema quirk that `js-yaml` accepts but GitHub's form renderer rejects, GitHub silently falls back to a blank issue for that template. The reviewer render check above is the mitigation > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used Claude Opus 4.7 — provider Anthropic, exact model ID `claude-opus-4-7`, extended-thinking + tool use, running inside the Paperclip Claude Code harness. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above (refs #7575, #4189) - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass (n/a — `.github/ISSUE_TEMPLATE/` content only; `js-yaml` parse check run instead) - [ ] I have added or updated tests where applicable (n/a — repo has no test coverage for `.github/` content) - [ ] If this change affects the UI, I have included before/after screenshots (n/a — only the GitHub.com "New issue" page is affected; render check happens post-merge on github.com) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (will verify after open) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (greploop will run after open) - [x] I will address all Greptile and reviewer comments before requesting merge --- .github/ISSUE_TEMPLATE/bug_report.yml | 105 ++++++++++++++++++++- .github/ISSUE_TEMPLATE/docs_issue.yml | 44 +++++++++ .github/ISSUE_TEMPLATE/enhancement.yml | 92 ++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 16 ++++ 4 files changed, 254 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/docs_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/enhancement.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 6109c8de..bf06469f 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -6,14 +6,34 @@ body: 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. + 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: @@ -21,17 +41,19 @@ body: 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. + 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: @@ -40,6 +62,7 @@ body: placeholder: e.g. 0.42.0 or 78dc3625ac validations: required: true + - type: dropdown id: deployment attributes: @@ -51,25 +74,101 @@ body: - 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. + 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/docs_issue.yml b/.github/ISSUE_TEMPLATE/docs_issue.yml new file mode 100644 index 00000000..00acd18a --- /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] +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 00000000..dde3af63 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/enhancement.yml @@ -0,0 +1,92 @@ +name: Enhancement proposal +description: Propose an improvement to an existing Paperclip feature +labels: [enhancement] +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 + description: Please confirm each of these before filing. + 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 index 39d0a067..e4e09edc 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -6,6 +6,22 @@ body: 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: