From 5c56f8787cb71593f09a580557e0922c81420135 Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:28:49 -0700 Subject: [PATCH 1/4] add github contribution templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 68 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 33 +++++++++++ .github/pull_request_template.md | 25 ++++++++ AGENTS.md | 48 +++++++++++++++ 5 files changed, 175 insertions(+) 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/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..739ac18 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,68 @@ +name: Bug report +description: Report broken behavior, a regression, or an unexpected failure. +labels: + - bug +body: + - type: markdown + attributes: + value: | + Search open and closed issues first, and keep the report focused on one problem. + + Redact private endpoint URLs, authorization headers, cookies, webhook payload secrets, forwarding destinations, and other credentials from all examples and evidence. + + - type: textarea + id: current-behavior + attributes: + label: Current behavior + description: Explain what happened, including any error messages or visible symptoms. + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected behavior + description: Explain what you expected to happen instead. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: Provide the smallest reliable reproduction you have. + placeholder: | + 1. + 2. + 3. + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Affected area + description: Select the part of webhooks.lol where the problem appears. + options: + - Web inspector + - Webhook capture or API + - CLI + - Endpoint forwarding or worker + - Documentation + - Deployment or infrastructure + - Other + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Include relevant browser, OS, whlol, Node.js, deployment, or runtime versions. + placeholder: Chrome 140 on macOS 26, or whlol 1.0 with Node.js 24 on Ubuntu 24.04 + + - type: textarea + id: evidence + attributes: + label: Additional evidence + description: Add relevant screenshots, recordings, logs, or sanitized request examples. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..c01b9fa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: Feature request +description: Propose a focused improvement or new capability. +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Search open and closed issues first, and keep the request focused on one change. + + Redact private endpoint URLs, authorization headers, cookies, webhook payload secrets, forwarding destinations, and other credentials from all examples and evidence. + + - type: textarea + id: problem + attributes: + label: Problem or goal + description: Explain what is difficult, missing, or not possible today. + validations: + required: true + + - type: textarea + id: outcome + attributes: + label: Desired outcome + description: Describe the proposed behavior and the acceptance criteria that would make the request complete. + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context + description: Add related issues, sanitized examples, screenshots, mockups, or references. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..266f5ae --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +## What Changed + + + +## Why + + + +## User-Facing Changes + + + +## Operational Notes + + + +## Validation + + diff --git a/AGENTS.md b/AGENTS.md index 26c6bcd..91af2c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,6 +108,54 @@ Railway deployments use app-local config-as-code files: pnpm workspace packages resolve correctly, and point each Railway service at its own config file path. Do not add a root `railway.json` for this monorepo. +## Branches, Commits, and Pull Requests + +- Use plain lowercase kebab-case for branch names. Keep names descriptive and do + not include issue numbers, prefixes, or namespaces such as `feature/`, `fix/`, + usernames, or agent names. +- Before every commit or amend, show the exact current diff and validation, then + get explicit approval. Branch or pull-request requests are not commit approval; + later changes require fresh approval. +- Never amend, rebase, squash, reset, rewrite history, or force-push without + explicit approval for that exact operation. +- Write commit messages entirely lowercase. Use the imperative mood for the + subject, keep each commit focused on one logical change, do not use type or + scope prefixes, and do not end the subject with a period. Add a body when the + reason or important tradeoffs are not clear from the subject. +- Keep each pull request focused on one coherent change. +- Write concise, specific, imperative pull request titles in sentence case. Do + not use prefixes or trailing periods, and make the title understandable without + the branch name. +- Pull request descriptions must include `What Changed`, `Why`, and `Validation`. + Include `User-Facing Changes` for browser UI, CLI output, or API behavior + changes. Include `Operational Notes` for migrations, configuration changes, + deployment ordering, or queue and worker implications. Remove optional sections + when they do not apply. +- Link related issues in the pull request description; do not include issue + numbers in branch names. +- Review the complete diff before opening a pull request. Update the title and + description whenever the scope changes, and remove unrelated changes. + +## Issues + +- Search open and closed issues before creating a new issue. +- Keep each issue focused on one problem or change. +- Use a concise, specific, sentence-case title without type prefixes. +- Give enough context to understand the issue without first inspecting the code. +- For bugs, describe the current and expected behavior. Include reproduction + steps, the affected product area, relevant environment details, and supporting + evidence when available. +- For enhancements, explain the problem or goal, the desired outcome, and clear + acceptance criteria. +- For browser UI issues, include screenshots. Include a short recording when + motion or interaction is relevant. For CLI issues, include representative + terminal output when useful. +- Redact private endpoint URLs, authorization headers, cookies, webhook payload + secrets, forwarding destinations, and other credentials from issue content. +- Link related issues and pull requests. +- Apply the appropriate existing label when creating an issue: `bug` for bugs and + `enhancement` for feature requests. + ## Database Workflow - Database table definitions live in `packages/database/src/auth-schema.ts` and From dd25a63c0aae1ab401806486122ea24880a5153d Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:32:10 -0700 Subject: [PATCH 2/4] align contribution templates with bitdream --- .github/ISSUE_TEMPLATE/bug_report.yml | 44 ++++--------------- .github/ISSUE_TEMPLATE/feature_request.yml | 10 ++--- .github/pull_request_template.md | 19 +++----- AGENTS.md | 50 ++++++---------------- 4 files changed, 31 insertions(+), 92 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 739ac18..2720a11 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ name: Bug report -description: Report broken behavior, a regression, or an unexpected failure. +description: Report broken behavior, a regression, or a crash. labels: - bug body: @@ -8,21 +8,11 @@ body: value: | Search open and closed issues first, and keep the report focused on one problem. - Redact private endpoint URLs, authorization headers, cookies, webhook payload secrets, forwarding destinations, and other credentials from all examples and evidence. - - type: textarea - id: current-behavior + id: description attributes: - label: Current behavior - description: Explain what happened, including any error messages or visible symptoms. - validations: - required: true - - - type: textarea - id: expected-behavior - attributes: - label: Expected behavior - description: Explain what you expected to happen instead. + label: Description + description: Explain what happened and what you expected to happen. validations: required: true @@ -35,34 +25,16 @@ body: 1. 2. 3. - validations: - required: true - - - type: dropdown - id: area - attributes: - label: Affected area - description: Select the part of webhooks.lol where the problem appears. - options: - - Web inspector - - Webhook capture or API - - CLI - - Endpoint forwarding or worker - - Documentation - - Deployment or infrastructure - - Other - validations: - required: true - - type: textarea + - type: input id: environment attributes: label: Environment - description: Include relevant browser, OS, whlol, Node.js, deployment, or runtime versions. - placeholder: Chrome 140 on macOS 26, or whlol 1.0 with Node.js 24 on Ubuntu 24.04 + description: Include the browser, OS, webhooks.lol or whlol version, and Node.js version when known. + placeholder: Chrome on macOS 26, webhooks.lol 1.0, whlol 1.0, Node.js 24 - type: textarea id: evidence attributes: label: Additional evidence - description: Add relevant screenshots, recordings, logs, or sanitized request examples. + description: Add relevant screenshots, recordings, logs, or request examples. Redact sensitive information. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index c01b9fa..2e3d634 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -8,8 +8,6 @@ body: value: | Search open and closed issues first, and keep the request focused on one change. - Redact private endpoint URLs, authorization headers, cookies, webhook payload secrets, forwarding destinations, and other credentials from all examples and evidence. - - type: textarea id: problem attributes: @@ -19,10 +17,10 @@ body: required: true - type: textarea - id: outcome + id: proposal attributes: - label: Desired outcome - description: Describe the proposed behavior and the acceptance criteria that would make the request complete. + label: Proposed change + description: Describe the desired behavior and what would make the request complete. validations: required: true @@ -30,4 +28,4 @@ body: id: context attributes: label: Additional context - description: Add related issues, sanitized examples, screenshots, mockups, or references. + description: Add related issues, screenshots, mockups, examples, or references. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 266f5ae..4d0d7ca 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,20 +6,13 @@ -## User-Facing Changes +## UI Changes - - -## Operational Notes - - + ## Validation - + diff --git a/AGENTS.md b/AGENTS.md index 91af2c9..585cbbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,31 +110,15 @@ own config file path. Do not add a root `railway.json` for this monorepo. ## Branches, Commits, and Pull Requests -- Use plain lowercase kebab-case for branch names. Keep names descriptive and do - not include issue numbers, prefixes, or namespaces such as `feature/`, `fix/`, - usernames, or agent names. -- Before every commit or amend, show the exact current diff and validation, then - get explicit approval. Branch or pull-request requests are not commit approval; - later changes require fresh approval. -- Never amend, rebase, squash, reset, rewrite history, or force-push without - explicit approval for that exact operation. -- Write commit messages entirely lowercase. Use the imperative mood for the - subject, keep each commit focused on one logical change, do not use type or - scope prefixes, and do not end the subject with a period. Add a body when the - reason or important tradeoffs are not clear from the subject. +- Use plain lowercase kebab-case for branch names. Keep names descriptive and do not include issue numbers, prefixes, or namespaces such as `feature/`, `fix/`, usernames, or agent names. +- Before every commit or amend, show the exact current diff and validation, then get explicit approval. Branch or pull-request requests are not commit approval; later changes require fresh approval. +- Never amend, rebase, squash, reset, rewrite history, or force-push without explicit approval for that exact operation. +- Write commit messages entirely lowercase. Use the imperative mood for the subject, keep each commit focused on one logical change, do not use type or scope prefixes, and do not end the subject with a period. Add a body when the reason or important tradeoffs are not clear from the subject. - Keep each pull request focused on one coherent change. -- Write concise, specific, imperative pull request titles in sentence case. Do - not use prefixes or trailing periods, and make the title understandable without - the branch name. -- Pull request descriptions must include `What Changed`, `Why`, and `Validation`. - Include `User-Facing Changes` for browser UI, CLI output, or API behavior - changes. Include `Operational Notes` for migrations, configuration changes, - deployment ordering, or queue and worker implications. Remove optional sections - when they do not apply. -- Link related issues in the pull request description; do not include issue - numbers in branch names. -- Review the complete diff before opening a pull request. Update the title and - description whenever the scope changes, and remove unrelated changes. +- Write concise, specific, imperative pull request titles in sentence case. Do not use prefixes or trailing periods, and make the title understandable without the branch name. +- Pull request descriptions must include `What Changed`, `Why`, and `Validation`. Include `UI Changes` only when the pull request changes the UI. Keep descriptions concise, self-contained, complete, and accurate to the final diff. +- Link any related issues in the pull request description; do not include issue numbers in branch names. +- Review the complete diff before opening a pull request. Update the title and description whenever the scope changes, and remove unrelated changes. ## Issues @@ -142,19 +126,11 @@ own config file path. Do not add a root `railway.json` for this monorepo. - Keep each issue focused on one problem or change. - Use a concise, specific, sentence-case title without type prefixes. - Give enough context to understand the issue without first inspecting the code. -- For bugs, describe the current and expected behavior. Include reproduction - steps, the affected product area, relevant environment details, and supporting - evidence when available. -- For enhancements, explain the problem or goal, the desired outcome, and clear - acceptance criteria. -- For browser UI issues, include screenshots. Include a short recording when - motion or interaction is relevant. For CLI issues, include representative - terminal output when useful. -- Redact private endpoint URLs, authorization headers, cookies, webhook payload - secrets, forwarding destinations, and other credentials from issue content. -- Link related issues and pull requests. -- Apply the appropriate existing label when creating an issue: `bug` for bugs and - `enhancement` for feature requests. +- For bugs, describe the current and expected behavior. Include reproduction steps, environment details, and supporting evidence when available. +- For enhancements, explain the problem or goal, the desired outcome, and clear acceptance criteria. +- For UI issues, include screenshots. Include a short video when motion or interaction is relevant. +- Link any related issues and pull requests. +- Apply the appropriate existing labels when creating an issue: `bug` for bugs and `enhancement` for feature requests. ## Database Workflow From 4cd43662459c68177c7a9ec2e116b139016814e0 Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:40:09 -0700 Subject: [PATCH 3/4] remove invented environment details --- .github/ISSUE_TEMPLATE/bug_report.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 2720a11..610a527 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -30,8 +30,7 @@ body: id: environment attributes: label: Environment - description: Include the browser, OS, webhooks.lol or whlol version, and Node.js version when known. - placeholder: Chrome on macOS 26, webhooks.lol 1.0, whlol 1.0, Node.js 24 + description: Include relevant environment details when known. - type: textarea id: evidence From dcd766ed9ad14d206c4a8162f39fcc43e4da900b Mon Sep 17 00:00:00 2001 From: Austin Smith Date: Sat, 11 Jul 2026 16:45:30 -0700 Subject: [PATCH 4/4] remove environment field --- .github/ISSUE_TEMPLATE/bug_report.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 610a527..3cabe61 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -26,12 +26,6 @@ body: 2. 3. - - type: input - id: environment - attributes: - label: Environment - description: Include relevant environment details when known. - - type: textarea id: evidence attributes: