Arnike/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(github): expand issue forms (#7628)

Browse Source 
## 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
This commit is contained in:
Devin Foley
2026-06-05 22:27:12 -07:00
committed by GitHub
parent d5889919a9
commit a4fa0eaf5e
4 changed files with 254 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.yml
+102 -3
View File
@@ -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
.github/ISSUE_TEMPLATE/docs_issue.yml
+44
View File
@@ -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.
.github/ISSUE_TEMPLATE/enhancement.yml
+92
View File
@@ -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.
.github/ISSUE_TEMPLATE/feature_request.yml
+16
View File
@@ -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: