104 lines
5.6 KiB
Markdown
104 lines
5.6 KiB
Markdown
# Player bug reports
|
|
|
|
The header's **Send bug report** button opens `/support`. Players can report a
|
|
bug with an optional PNG, JPEG, or WebP screenshot up to 5 MB. Each submitted
|
|
report creates one Medium-priority issue in Linear. Retries reuse server-generated
|
|
issue and comment IDs. Screenshots are normalized, stripped of metadata, and
|
|
uploaded to private Supabase Storage and Linear assets.
|
|
|
|
Signed-in players keep reports in their account. Guests keep access through a
|
|
180-day HttpOnly browser cookie. A guest can sign in in the same browser and
|
|
choose **Keep this report in my account**. Clearing the cookie before linking
|
|
loses guest access. Conversations and screenshots are private.
|
|
|
|
## Linear commands
|
|
|
|
Add a new comment on the report's issue beginning with:
|
|
|
|
```text
|
|
#player-report-send Dear user, we found the bug. Thank you for reporting it!
|
|
```
|
|
|
|
The text after the prefix appears in the player's conversation. Other staff
|
|
comments remain internal. Player follow-ups appear in Linear with
|
|
`#user-report-message`; the initial report uses the same prefix in its description.
|
|
Editing an existing comment does not send another message.
|
|
|
|
Players can select **Close report** after support has received it. The conversation
|
|
shows **Done**, becomes read-only, and displays its deletion date. MineGeo moves
|
|
the matching Linear issue to the team's **Done** status. Staff can also post the
|
|
exact command `#player-report-close`, or move the issue to Done in Linear.
|
|
|
|
Three days after closing, a durable Vercel Workflow deletes the Linear issue,
|
|
both the original and normalized Supabase screenshots, the local report, and its
|
|
messages. It runs even when nobody visits support. Linear's normal deleted-issue
|
|
trash retention still applies. Username glow and Bug finder rewards already
|
|
granted to an account remain. Guest rewards must be linked before the report is
|
|
deleted. Reopening the issue in Linear before cleanup starts cancels deletion;
|
|
closing it again starts a new three-day period. Repeated close requests and
|
|
replayed staff commands do not extend the existing deadline.
|
|
|
|
To grant or remove the actual account reward, add a separate new comment:
|
|
|
|
```text
|
|
#player-report-glow grant
|
|
#player-report-glow revoke
|
|
```
|
|
|
|
Use one command per comment. A guest reward is held until the report is linked
|
|
to an account. The glow appears beside account names on the dashboard, settings,
|
|
leaderboard, and public map credits. Only verified Linear webhook commands can
|
|
change rewards; browser writes cannot grant them.
|
|
|
|
The follow-up migration `20261008075322_profile_identity.sql` adds a permanent
|
|
**Bug finder** badge when a glow is granted. Revoking the glow preserves the badge.
|
|
Guest reports retain confirmed-bug recognition when linked after a glow revoke.
|
|
Players with an active glow can choose any hex color in **Settings → Username glow**.
|
|
Moderators display a shield badge, and Admins display a crown. Admins can find an account
|
|
in **Moderation → Player prefixes** to assign, change, or remove a custom text/icon
|
|
prefix. Account IDs disambiguate players with identical names. Prefixes do not
|
|
change permissions. These decorations appear in account views, leaderboards,
|
|
map credits, support conversations, and authenticated multiplayer rosters and chat. Guests cannot gain
|
|
badges by copying a registered player's display name.
|
|
|
|
## Deployment setup
|
|
|
|
Apply `20261008071054_bug_reports.sql`, `20261008075322_profile_identity.sql`, and
|
|
`20261010053310_bug_report_retention.sql`
|
|
before deploying. Production environment
|
|
variables in Vercel:
|
|
|
|
- `LINEAR_API_KEY`: sensitive personal API key with **Read and Write** access to
|
|
the support team. Create issues/comments alone cannot update status or delete
|
|
issues. If needed, create a replacement in Linear **Settings → Security & access
|
|
→ Personal API keys**, then replace this variable in Vercel **Production** and
|
|
redeploy. Never paste the key into chat.
|
|
- `LINEAR_WEBHOOK_SECRET`: sensitive signing secret of the team's Linear webhook.
|
|
- `LINEAR_TEAM_ID`: support team UUID.
|
|
- `LINEAR_PROJECT_ID`: optional project UUID or Linear project identifier.
|
|
|
|
Enable **Comment and Issue** events on the team webhook and set its URL to
|
|
`https://minegeo.vercel.app/api/support/linear`. Redeploy after saving environment
|
|
variables. Keys stay server-side and must never be pasted into issue descriptions,
|
|
client configuration, or source uploads.
|
|
|
|
Webhook requests require a matching raw-body HMAC signature and a timestamp
|
|
within 60 seconds. Duplicate events have no effect. Delivery to Linear happens
|
|
after the HTTP response; opening the conversation retries interrupted or failed
|
|
delivery. The page shows saved/pending and delivered states.
|
|
Issue events immediately synchronize Done/reopened states. Opening the inbox or
|
|
conversation also checks status, at most once per minute per report, as a fallback.
|
|
If Linear or Storage deletion fails, the local report is retained for retries;
|
|
the conversation shows a retry action if cleanup exhausts its automatic retries.
|
|
Keep Vercel's **Enable access to System Environment Variables** setting enabled
|
|
for durable timers. No additional secret or cron is needed.
|
|
|
|
Validation: `npm test`, `npm run typecheck`, `npm run build`, and
|
|
`node scripts/test-bug-reports-sql.mjs` (uses the isolated PGlite installation under
|
|
`.data/sql-verification`, as the other SQL verification scripts do).
|
|
`node scripts/test-bug-retention-http.mjs https://minegeo.vercel.app` verifies
|
|
the deployed flow with a clearly labeled temporary report and screenshot. It
|
|
checks ownership, Done synchronization, the three-day deadline, and deletion
|
|
from both systems by advancing only that test report's deadline. The fixture ID
|
|
is journaled under the ignored `.data/retention-check` directory for recovery.
|