From 0ca20fd8f35dd63c94857fb868e1648a10f263ea Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 11 May 2026 07:53:44 +0000 Subject: [PATCH] chore: add issue forms and PR template structured bug/feature/api-regression issue forms and a PR template that forces the info needed to actually review a change: version, repro, how-to-verify steps, and a sparkle/release checklist guarding the auto-update bricking rules in CLAUDE.md. --- .github/ISSUE_TEMPLATE/api_regression.yml | 54 ++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 117 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 55 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 60 +++++++++++ 5 files changed, 294 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/api_regression.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/api_regression.yml b/.github/ISSUE_TEMPLATE/api_regression.yml new file mode 100644 index 00000000..612cf24d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/api_regression.yml @@ -0,0 +1,54 @@ +name: Upstream API regression +description: Claude `/api/oauth/usage` or Codex `/wham/usage` started returning unexpected fields, errors, or shape changes. +title: "fix(usage): returning " +labels: ["bug", "upstream-api"] +body: + - type: markdown + attributes: + value: | + Both upstream endpoints are undocumented and change without notice. This template captures what's needed to update the parser. + + **Redact your bearer token before posting any `curl` output.** + + - type: dropdown + id: endpoint + attributes: + label: Which endpoint? + options: + - Claude — `/api/oauth/usage` + - Codex — `/wham/usage` + - Claude OAuth refresh — `platform.claude.com/v1/oauth/token` + validations: + required: true + + - type: input + id: app-version + attributes: + label: CodexIsland version + placeholder: "0.0.42" + validations: + required: true + + - type: textarea + id: symptom + attributes: + label: What does the chip show now? + placeholder: "HTTP 403 / `auth required` / wrong percentage / missing plan badge" + validations: + required: true + + - type: textarea + id: curl + attributes: + label: Raw response + description: | + Paste the JSON body of the actual API response (token redacted). For Claude, include the request headers you used — the endpoint gates on `User-Agent: claude-code/X.Y.Z` and the `oauth-2025-04-20` beta header. + render: json + validations: + required: true + + - type: textarea + id: when + attributes: + label: When did it start? + description: Approximate date/time. If a model change or Anthropic announcement preceded it, link it. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..239f6b6a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,117 @@ +name: Bug report +description: Something is broken or behaves unexpectedly. +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug. The more of the fields below you fill in, the faster this gets fixed. + + Before filing: please search [existing issues](https://github.com/ericjypark/codex-island/issues?q=is%3Aissue) to avoid duplicates. + + - type: input + id: app-version + attributes: + label: CodexIsland version + description: Click the menu bar chip → About, or run `defaults read dev.codexisland.CodexIsland CFBundleShortVersionString`. + placeholder: "0.0.42" + validations: + required: true + + - type: input + id: macos-version + attributes: + label: macOS version + description: Output of `sw_vers -productVersion`. Include chip (Apple Silicon / Intel) if you know it. + placeholder: "14.5 (Apple Silicon)" + validations: + required: true + + - type: dropdown + id: install-method + attributes: + label: How did you install? + options: + - Homebrew cask (`brew install --cask ericjypark/tap/codexisland`) + - DMG download from Releases + - Built from source (`./build.sh`) + - Auto-updated from a previous version + - Not sure + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: One or two sentences. What you were doing and what went wrong. + placeholder: "Opened settings → toggled X → the chip showed `HTTP 403` instead of token usage." + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Reproduction steps + description: Numbered steps. If it's intermittent, say how often it happens. + placeholder: | + 1. Launch the app + 2. ... + 3. ... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Which part of the app? + multiple: true + options: + - Window placement / notch detection + - Settings panel + - Claude usage chip + - Codex usage chip + - Auto-update (Sparkle) + - SparkChart / history + - Launch at login + - Build / install + - Other + validations: + required: true + + - type: textarea + id: usage-state + attributes: + label: Was usage data populated before the bug? + description: | + If this is a usage-chip bug — was the chip showing real numbers before? `auth required` or `HTTP 4xx` errors usually mean upstream creds are missing/expired, not an app bug. Try `claude /login` (or re-login to Codex) before filing. + placeholder: "Claude was showing 47% before; suddenly flipped to HTTP 403 after the app updated to 0.0.42." + + - type: textarea + id: defaults + attributes: + label: Settings dump (optional, for settings/UI bugs) + description: Output of `defaults read dev.codexisland.CodexIsland`. Redact anything sensitive. + render: shell + + - type: textarea + id: logs + attributes: + label: Console logs (optional) + description: | + Open Console.app → search "CodexIsland" → copy any errors from the timeframe of the bug. For Sparkle update bugs, also include `Sparkle` lines. + render: shell + + - type: textarea + id: extra + attributes: + label: Anything else? + description: Screenshots, recordings, related issues, theories. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..f89c8f0e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Question or discussion + url: https://github.com/ericjypark/codex-island/discussions + about: Open-ended questions, ideas, or "is this expected?" — start a discussion instead of an issue. + - name: Security disclosure + url: https://github.com/ericjypark/codex-island/security/advisories/new + about: Report a vulnerability privately. Do NOT open a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..69e8ce9d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,55 @@ +name: Feature request +description: Suggest a new capability or a change to existing behavior. +title: "feat: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Before filing: search [existing issues](https://github.com/ericjypark/codex-island/issues?q=is%3Aissue) and the [Things that need work](https://github.com/ericjypark/codex-island/blob/main/CONTRIBUTING.md#things-that-need-work) list — your idea might already be tracked. + + For open-ended "what if" ideas, a [Discussion](https://github.com/ericjypark/codex-island/discussions) is a better starting point than an issue. + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the user-facing pain. Skip the proposed solution for now — focus on the symptom. + placeholder: "I have two notched displays and only one shows the panel, so I can't see usage when I'm working on the other monitor." + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: What would you like the app to do? UI sketches, mock chip text, or rough behavior is fine. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about and why you rejected them. Keeps the discussion focused. + + - type: dropdown + id: scope + attributes: + label: Rough scope + description: Best guess — maintainer will adjust. + options: + - Small (a setting, a label, a one-file change) + - Medium (a new view or a refactor inside one subsystem) + - Large (touches build, Sparkle, or multiple subsystems) + - Not sure + validations: + required: true + + - type: checkboxes + id: willing + attributes: + label: Are you willing to help? + options: + - label: I can help test a build + - label: I can open a PR for this diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..f27cabcc --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,60 @@ + + +## What changed + + + +## Why + + + +## How to verify + + + +1. +2. +3. + +## Screenshots / recording + + + +## Risk + blast radius + + + +## Release impact + +- [ ] No version bump needed (code/doc change with no shipped behavior difference) +- [ ] Bumps `VERSION` (will trigger a Sparkle auto-update for every install on next CI run) +- [ ] Touches `build.sh`, `release.sh`, `scripts/setup-sparkle.sh`, or `.github/workflows/release.yml` + +## Pre-flight checklist + +- [ ] `./scripts/verify.sh` passes locally (builds + smoke-launches) +- [ ] Manually launched `./build/CodexIsland.app` and exercised the changed code path +- [ ] Commits follow lowercase Conventional Commits; no `Co-Authored-By` lines +- [ ] No banned vocab (comprehensive, delve, crucial, robust, seamless) in commits, comments, or docs +- [ ] No new comments added unless the *why* is non-obvious +- [ ] No files added under `Vendor/` (gitignored on purpose) +- [ ] Did **not** hand-edit `Casks/codexisland.rb` version/SHA, or any appcast XML + +### Sparkle / release-only PRs (skip if N/A) + +- [ ] `VERSION` is monotonic semver (e.g. `0.0.43`, never `1` or `100`) +- [ ] `SU_PUBLIC_KEY` in `build.sh` is **unchanged** (changing it bricks auto-update for every existing install — see CLAUDE.md hard rule #2) +- [ ] If bumping `VERSION`, also bumped it in [`ericjypark/codex-island-landing`](https://github.com/ericjypark/codex-island-landing) so the marketing site doesn't lag