From c76670ff6c50b825799b810cc90d109fc042194f Mon Sep 17 00:00:00 2001 From: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 Date: Fri, 24 Jul 2026 18:52:35 -0400 Subject: [PATCH 1/4] docs(contributing): overhaul contribution intake Add a PR template, restructure CONTRIBUTING.md with a 'Before You Open a PR' section, and replace the placeholder issue templates with GitHub issue forms. Changes: - New .github/PULL_REQUEST_TEMPLATE.md: duplicate-check field (fill-in closest existing PR/issue number), issue link, just-ci gate, one logical change reminder, and AI/agent disclosure checkbox. - CONTRIBUTING.md: add 'Before You Open a PR' section at the top covering duplicate-check policy, duplicate-triage policy, issue-first rule for features, agent-contribution policy, and PR title convention. Fix intro to point to issues (Discussions are disabled on block/buzz). Drop the now-redundant 'Before You Start' bullets from the PR section. Drop dangling ToC entry for MCP tool guide (section was never written). - .github/ISSUE_TEMPLATE/bug-report.yml: replace placeholder markdown template with a GitHub issue form; required fields for repro steps, expected/actual behavior, OS, Buzz version, and logs. - .github/ISSUE_TEMPLATE/feature-request.yml: new form with required duplicate-search field, problem statement, and proposed solution. - .github/ISSUE_TEMPLATE/config.yml: blank_issues_enabled: false; remove placeholder Discord contact link. Co-authored-by: Will Pfleger Signed-off-by: Will Pfleger --- .github/ISSUE_TEMPLATE/bug-report.md | 31 ------- .github/ISSUE_TEMPLATE/bug-report.yml | 74 +++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +- .github/ISSUE_TEMPLATE/feature-request.yml | 49 +++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 23 +++++ CONTRIBUTING.md | 97 ++++++++++++++++------ 6 files changed, 218 insertions(+), 61 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug-report.md create mode 100644 .github/ISSUE_TEMPLATE/bug-report.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.md b/.github/ISSUE_TEMPLATE/bug-report.md deleted file mode 100644 index 25f0bc5ed8..0000000000 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -name: 🐛 Bug Report -about: Thank you for taking the time, please report a reproducible bug -title: "[Bug] " -labels: bug -assignees: add codeowner's @name here - ---- - -**Describe the bug** -*A clear and concise description of what the bug is.* - -**To Reproduce:** -*Steps to reproduce the behavior:* -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior:** -*A clear and concise description of what you expected to happen.* - -**Supporting Material** -*If applicable, add screenshots, output log and/or other documentation to help explain your problem.* - -**Environment (please complete the following information):** - - OS: [ex: iOS] - - Version - -**Additional context** -Add any other context that you feel is relevant about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000000..00c35f6201 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,74 @@ +name: 🐛 Bug Report +description: Report a reproducible bug in Buzz +title: "[Bug] " +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to report a bug! Please fill in as much detail as you can — a clear repro is the fastest path to a fix. + + - type: textarea + id: description + attributes: + label: What happened? + description: A clear and concise description of the bug. + placeholder: "When I do X, Y happens instead of Z." + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Step-by-step instructions to reproduce the behavior. + placeholder: | + 1. Open Buzz and navigate to ... + 2. Click ... + 3. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect to happen? + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating system + options: + - macOS + - Linux + - Windows + - iOS + - Android + - Other + validations: + required: true + + - type: input + id: version + attributes: + label: Buzz version + description: "Find this in Help → About, or run `buzz --version`." + placeholder: "e.g. 0.4.2" + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs / error output + description: Paste any relevant logs or error messages here. + render: shell + + - type: textarea + id: additional + attributes: + label: Additional context + description: Screenshots, screen recordings, or anything else that helps explain the problem. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 0ba9db2532..3ba13e0cec 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1 @@ -contact_links: - - name: ❓ Questions and Help 🤔 - url: https://discord.gg/block-opensource (/add your discord channel if applicable) - about: This issue tracker is not for support questions. Please refer to the community for more help. +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000000..07741d3797 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,49 @@ +name: 💡 Feature Request +description: Propose a new feature or improvement +title: "[Feature] " +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Before opening a feature request, please [search open issues and PRs](https://github.com/block/buzz/issues?q=is%3Aopen) — someone may have already proposed or started work on the same idea. + + Features need an issue with maintainer acknowledgment before a PR. Opening this issue is the first step. + + - type: input + id: existing + attributes: + label: Closest existing issue or PR + description: "What's the most similar open issue or PR you found? Write the number, or \"none found\"." + placeholder: "#1234 or none found" + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem statement + description: What problem does this solve? Who runs into it and when? + placeholder: "As a [user type], I often need to [do X] but currently have to [workaround Y], which is frustrating because..." + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: Describe what you'd like to see. Concrete examples, mockups, or API sketches are very helpful. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What other approaches did you consider? Why do you prefer this one? + + - type: textarea + id: additional + attributes: + label: Additional context + description: Links, screenshots, prior art in other tools, or anything else that helps. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..d27d36f244 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ + + +## What does this PR do? + + + +## Related issue + + + +Fixes # + +## Checklist + +- [ ] I searched [open PRs](https://github.com/block/buzz/pulls) and [issues](https://github.com/block/buzz/issues) for duplicates — closest existing: # +- [ ] `just ci` passes locally +- [ ] This PR contains one logical change (separate unrelated changes into separate PRs) +- [ ] New behavior has tests; bug fixes include a regression test +- [ ] Docs updated if this adds or changes a public API, event kind, MCP tool, or config variable +- [ ] **AI/agent-assisted?** If any part of this PR was generated by an AI tool or agent: I personally verified the change builds and behaves as described, I searched for duplicates, and I will respond to review feedback. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6278f5eba..c890471377 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Welcome, and thank you for your interest in contributing! Buzz is an open-source project and we're glad you're here. This guide will help you get from zero to a merged pull request. -If you have questions that aren't answered here, open a GitHub Discussion or +If you have questions that aren't answered here, open a GitHub issue or reach out in the community channels. --- @@ -12,14 +12,14 @@ reach out in the community channels. ## Table of Contents 1. [Code of Conduct](#code-of-conduct) -2. [Setting Up the Development Environment](#setting-up-the-development-environment) -3. [Running Tests](#running-tests) -4. [Code Style](#code-style) -5. [Making a Pull Request](#making-a-pull-request) -6. [Architecture Overview](#architecture-overview) -7. [Ecosystem](#ecosystem) -8. [How to Add a New Event Kind](#how-to-add-a-new-event-kind) -9. [How to Add a New MCP Tool](#how-to-add-a-new-mcp-tool) +2. [Before You Open a PR](#before-you-open-a-pr) +3. [Setting Up the Development Environment](#setting-up-the-development-environment) +4. [Running Tests](#running-tests) +5. [Code Style](#code-style) +6. [Making a Pull Request](#making-a-pull-request) +7. [Architecture Overview](#architecture-overview) +8. [Ecosystem](#ecosystem) +9. [How to Add a New Event Kind](#how-to-add-a-new-event-kind) 10. [How to Add a New API Endpoint](#how-to-add-a-new-api-endpoint) 11. [License and CLA](#license-and-cla) @@ -33,6 +33,68 @@ unacceptable behavior to **conduct@buzz-relay.org**. --- +## Before You Open a PR + +This section exists to help your PR land quickly. The most common reason +PRs are closed without review is a duplicate — there's already an open PR +or issue for the same thing. + +### Check for duplicates first + +Search [open PRs](https://github.com/block/buzz/pulls) and +[open issues](https://github.com/block/buzz/issues) before you start. +When you open your PR, name the closest existing one in the description +(or "none found"). That one field saves maintainers a lot of triage time. + +**Duplicate-triage policy:** when two PRs address the same thing, the +earlier one wins unless the later one is clearly more complete. Duplicates +are closed with a pointer to the surviving PR — no hard feelings, just +keeping the queue manageable. + +### Features need an issue first + +For anything beyond a typo fix, doc improvement, or obvious bug: + +1. Open an issue describing the problem and proposed solution. +2. Wait for a maintainer to acknowledge the approach (a comment or label is enough). +3. Comment on the issue to claim it — so two people don't build the same thing. +4. Then open a PR. + +Small fixes (typos, doc improvements, obvious bugs with clear fixes) can +skip straight to a PR. + +### AI / agent-assisted contributions + +Buzz is an agent platform — AI-assisted PRs are welcome and encouraged. +But the **human submitter is accountable**: you personally verified the +change builds and behaves as described, you searched for duplicates, and +you will respond to review feedback. Unattended agent-generated PRs that +don't meet this bar will be closed without detailed review. The PR +template has a checkbox for this — please use it honestly. + +### Duplicate-check in your PR template + +The PR template will ask you to name the closest existing PR or issue. +This isn't a formality — it's the main mechanism that keeps us from +reviewing the same change five times. + +### PR titles follow Conventional Commits + +We squash-merge, so your PR title becomes the commit subject in `main`. +Follow the same format as commit messages: + +``` +feat(mcp): add get_feed_actions tool +fix(auth): reject expired NIP-42 challenges +docs(contributing): add duplicate-check policy +``` + +The type prefix (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`) is +required. See the [Commit Messages](#commit-messages) section for the +full reference. + +--- + ## Setting Up the Development Environment ### Prerequisites @@ -248,13 +310,6 @@ required. The scope (in parentheses) is optional but encouraged. ## Making a Pull Request -### Before You Start - -- Check open issues and PRs to avoid duplicate work. -- For significant changes, open an issue first to discuss the approach. -- For small fixes (typos, doc improvements, obvious bugs), go ahead and open - a PR directly. - ### What a Good PR Looks Like 1. **Focused** — one logical change per PR. If you're fixing a bug and @@ -275,16 +330,6 @@ required. The scope (in parentheses) is optional but encouraged. - How to test it manually (if applicable) - Any follow-up work deferred to a future PR -### PR Checklist - -``` -- [ ] `just ci` passes (fmt + clippy + unit tests + mobile) -- [ ] Integration tests pass (`just test`) -- [ ] New public APIs / tools / endpoints are documented -- [ ] No new `unwrap()` in production code paths -- [ ] No new `unsafe` blocks -``` - ### Review Process - A maintainer will review your PR within a few business days. From 9961b8f0b86acf562ca04c268a25025f05217a1b Mon Sep 17 00:00:00 2001 From: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 Date: Fri, 24 Jul 2026 19:34:05 -0400 Subject: [PATCH 2/4] docs(contributing): revise tone, fix intake gaps, add question form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply review feedback from pass 1: - Rewrite 'Before You Open a PR' to lead with contributor benefit (two-minute search saves duplicate work) rather than closure stats; drop the hard four-step permission gate and 'Duplicate-check in your PR template' subsection; soften agent-policy to 'may be closed with a pointer'; issue-first is now a strong recommendation, not a gate - Fix intro to route questions to the new question.yml form instead of a dead 'community channels' link - Restore 'How to Add a New MCP Tool' ToC entry (#2612 owns the section body; this restores the pre-existing entry) - Replace 'within a few business days' review SLA with capacity-honest language - PR template: issue-first wording → recommendation; replace conditional AI checkbox with explicit fill-in field; add conditional integration test item (just ci does not run just test); fix '#' prefix on duplicate field; fix bare 'Fixes #' line - bug-report.yml: point version field to Desktop Settings footer; drop buzz --version (flag does not exist); allow 'unknown' - feature-request.yml: issue-first wording → recommendation - Add question.yml issue form with two required fields (what/tried) and optional environment; links question route end-to-end Co-authored-by: Will Pfleger Signed-off-by: Will Pfleger --- .github/ISSUE_TEMPLATE/bug-report.yml | 4 +- .github/ISSUE_TEMPLATE/feature-request.yml | 2 +- .github/ISSUE_TEMPLATE/question.yml | 34 +++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 12 +++-- CONTRIBUTING.md | 56 +++++++++------------- 5 files changed, 68 insertions(+), 40 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/question.yml diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 00c35f6201..d579901e52 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -55,8 +55,8 @@ body: id: version attributes: label: Buzz version - description: "Find this in Help → About, or run `buzz --version`." - placeholder: "e.g. 0.4.2" + description: "Find this at the bottom of the Settings sidebar (Desktop). Write \"unknown\" if you can't determine it." + placeholder: "e.g. 0.4.2 or unknown" validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index 07741d3797..d7ad3e46a8 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -8,7 +8,7 @@ body: value: | Before opening a feature request, please [search open issues and PRs](https://github.com/block/buzz/issues?q=is%3Aopen) — someone may have already proposed or started work on the same idea. - Features need an issue with maintainer acknowledgment before a PR. Opening this issue is the first step. + Opening an issue first (before a PR) is strongly recommended for new features — it's the best way to avoid spending a weekend on something someone else is already building. - type: input id: existing diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000000..2c75b1880a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,34 @@ +name: ❓ Question +description: Ask a question about using or contributing to Buzz +title: "[Question] " +labels: [question] +body: + - type: markdown + attributes: + value: | + Have a question? We're happy to help. Please check the [README](https://github.com/block/buzz#readme), [CONTRIBUTING.md](https://github.com/block/buzz/blob/main/CONTRIBUTING.md), and [open issues](https://github.com/block/buzz/issues) first — your answer may already be there. + + - type: textarea + id: question + attributes: + label: What are you trying to do? + description: Describe what you're trying to accomplish or understand. + placeholder: "I'm trying to..." + validations: + required: true + + - type: textarea + id: tried + attributes: + label: What have you tried or looked at? + description: Share what you've already attempted or where you've looked. This helps us give a more targeted answer. + placeholder: "I looked at... / I tried... but..." + validations: + required: true + + - type: input + id: environment + attributes: + label: Environment (optional) + description: OS, Buzz version, or other relevant context. + placeholder: "e.g. macOS 14, Buzz 0.4.2" diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d27d36f244..32da243d30 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,15 +9,19 @@ ## Related issue - + -Fixes # +Related issue: ## Checklist -- [ ] I searched [open PRs](https://github.com/block/buzz/pulls) and [issues](https://github.com/block/buzz/issues) for duplicates — closest existing: # +- [ ] I searched [open PRs](https://github.com/block/buzz/pulls) and [issues](https://github.com/block/buzz/issues) for duplicates — closest existing: - [ ] `just ci` passes locally +- [ ] Relevant integration tests pass (`just test`) — required for relay, database, or auth changes - [ ] This PR contains one logical change (separate unrelated changes into separate PRs) - [ ] New behavior has tests; bug fixes include a regression test - [ ] Docs updated if this adds or changes a public API, event kind, MCP tool, or config variable -- [ ] **AI/agent-assisted?** If any part of this PR was generated by an AI tool or agent: I personally verified the change builds and behaves as described, I searched for duplicates, and I will respond to review feedback. + +## AI / agent assistance + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c890471377..1e15a31172 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,8 @@ Welcome, and thank you for your interest in contributing! Buzz is an open-source project and we're glad you're here. This guide will help you get from zero to a merged pull request. -If you have questions that aren't answered here, open a GitHub issue or -reach out in the community channels. +If you have questions that aren't answered here, [open a question issue](https://github.com/block/buzz/issues/new?template=question.yml) +or reach out in the community channels. --- @@ -20,8 +20,9 @@ reach out in the community channels. 7. [Architecture Overview](#architecture-overview) 8. [Ecosystem](#ecosystem) 9. [How to Add a New Event Kind](#how-to-add-a-new-event-kind) -10. [How to Add a New API Endpoint](#how-to-add-a-new-api-endpoint) -11. [License and CLA](#license-and-cla) +10. [How to Add a New MCP Tool](#how-to-add-a-new-mcp-tool) +11. [How to Add a New API Endpoint](#how-to-add-a-new-api-endpoint) +12. [License and CLA](#license-and-cla) --- @@ -35,48 +36,37 @@ unacceptable behavior to **conduct@buzz-relay.org**. ## Before You Open a PR -This section exists to help your PR land quickly. The most common reason -PRs are closed without review is a duplicate — there's already an open PR -or issue for the same thing. +A two-minute search can save you from building something that's already in +review. Since launch we've had several people independently build the same +fix — a quick look at open PRs and issues first makes everyone's time count. ### Check for duplicates first Search [open PRs](https://github.com/block/buzz/pulls) and [open issues](https://github.com/block/buzz/issues) before you start. When you open your PR, name the closest existing one in the description -(or "none found"). That one field saves maintainers a lot of triage time. +(or "none found"). When two PRs address the same thing, we keep the earlier +one unless the later one is clearly more complete, and close the other with +a pointer. -**Duplicate-triage policy:** when two PRs address the same thing, the -earlier one wins unless the later one is clearly more complete. Duplicates -are closed with a pointer to the surviving PR — no hard feelings, just -keeping the queue manageable. +### Features: open an issue first (strongly recommended) -### Features need an issue first - -For anything beyond a typo fix, doc improvement, or obvious bug: - -1. Open an issue describing the problem and proposed solution. -2. Wait for a maintainer to acknowledge the approach (a comment or label is enough). -3. Comment on the issue to claim it — so two people don't build the same thing. -4. Then open a PR. +For anything beyond a typo fix, doc improvement, or obvious bug, opening +an issue first is the best way to avoid spending a weekend on something +someone else is already building. Describe the problem and proposed +solution, and comment to claim it once a maintainer has acknowledged the +approach — that way two people don't build the same thing in parallel. Small fixes (typos, doc improvements, obvious bugs with clear fixes) can -skip straight to a PR. +go straight to a PR. ### AI / agent-assisted contributions Buzz is an agent platform — AI-assisted PRs are welcome and encouraged. -But the **human submitter is accountable**: you personally verified the -change builds and behaves as described, you searched for duplicates, and -you will respond to review feedback. Unattended agent-generated PRs that -don't meet this bar will be closed without detailed review. The PR -template has a checkbox for this — please use it honestly. - -### Duplicate-check in your PR template - -The PR template will ask you to name the closest existing PR or issue. -This isn't a formality — it's the main mechanism that keeps us from -reviewing the same change five times. +The **human submitter is accountable**: you personally verified the change +builds and behaves as described, you searched for duplicates, and you will +respond to review feedback. PRs that don't meet this bar may be closed +with a pointer to this section. ### PR titles follow Conventional Commits @@ -332,7 +322,7 @@ required. The scope (in parentheses) is optional but encouraged. ### Review Process -- A maintainer will review your PR within a few business days. +- We prioritize focused PRs that follow this guide and review as capacity allows. - Address review comments by pushing new commits (don't force-push during review; it makes it hard to see what changed). - Once approved, a maintainer will squash-merge your PR. From 980d338f7192128fed813f2db7044b4d65541b66 Mon Sep 17 00:00:00 2001 From: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 Date: Fri, 24 Jul 2026 19:42:39 -0400 Subject: [PATCH 3/4] docs(contributing): soften issue-first wording, drop dangling channels ref - PULL_REQUEST_TEMPLATE.md: rewrite Related issue comment to say opening an issue is 'strongly recommended' (not required); remove the now-duplicate old line - CONTRIBUTING.md: remove 'or reach out in the community channels' from intro (no channel to link; question form is the route) Co-authored-by: Will Pfleger Signed-off-by: Will Pfleger --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- CONTRIBUTING.md | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 32da243d30..b631f08d0a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,9 +9,9 @@ ## Related issue - + -Related issue: +Related issue: ## Checklist diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e15a31172..0a69fc3a22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,7 @@ Welcome, and thank you for your interest in contributing! Buzz is an open-source project and we're glad you're here. This guide will help you get from zero to a merged pull request. -If you have questions that aren't answered here, [open a question issue](https://github.com/block/buzz/issues/new?template=question.yml) -or reach out in the community channels. +If you have questions that aren't answered here, [open a question issue](https://github.com/block/buzz/issues/new?template=question.yml). --- From 1ea8df57accc93f83ee0d55858a341cef1d4de5d Mon Sep 17 00:00:00 2001 From: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 Date: Fri, 24 Jul 2026 21:16:43 -0400 Subject: [PATCH 4/4] docs(contributing): trim to goose-scale minimal intake surface Replace 5-file, ~180-line template surface with a 4-file, ~50-line goose-modeled set: - PR template: drop checklist and AI-disclosure field; keep Summary, Related issue (with duplicate-check prompt), Testing - Issue templates: replace YAML forms with plain-markdown bug-report.md and feature-request.md; duplicate-check guidance lives in both the feature template footer and the PR template comment - config.yml: blank_issues_enabled: true (question form removed; questions route to blank issues) - CONTRIBUTING: compress 'Before You Open a PR' to four prose sentences covering duplicate search, issue-first recommendation, AI ownership, and review cadence; update intro link to plain /issues/new Co-authored-by: Will Pfleger Signed-off-by: Will Pfleger --- .github/ISSUE_TEMPLATE/bug-report.md | 24 +++++++ .github/ISSUE_TEMPLATE/bug-report.yml | 74 ---------------------- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/feature-request.md | 21 ++++++ .github/ISSUE_TEMPLATE/feature-request.yml | 49 -------------- .github/ISSUE_TEMPLATE/question.yml | 34 ---------- .github/PULL_REQUEST_TEMPLATE.md | 31 ++------- CONTRIBUTING.md | 49 ++------------ 8 files changed, 58 insertions(+), 226 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.md delete mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.md delete mode 100644 .github/ISSUE_TEMPLATE/feature-request.yml delete mode 100644 .github/ISSUE_TEMPLATE/question.yml diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000000..e383313452 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,24 @@ +--- +name: Bug report +about: Report a reproducible bug in Buzz +labels: bug +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**Steps to reproduce** +1. Go to '...' +2. Click on '...' +3. See error + +**Expected behavior** +What did you expect to happen? + +**Version and platform** +Find your version at the bottom of the Settings sidebar. Write "unknown" if you can't determine it. +- Buzz version: +- OS: + +**Logs / additional context** +Paste any relevant logs, error messages, or screenshots here. diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml deleted file mode 100644 index d579901e52..0000000000 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ /dev/null @@ -1,74 +0,0 @@ -name: 🐛 Bug Report -description: Report a reproducible bug in Buzz -title: "[Bug] " -labels: [bug] -body: - - type: markdown - attributes: - value: | - Thank you for taking the time to report a bug! Please fill in as much detail as you can — a clear repro is the fastest path to a fix. - - - type: textarea - id: description - attributes: - label: What happened? - description: A clear and concise description of the bug. - placeholder: "When I do X, Y happens instead of Z." - validations: - required: true - - - type: textarea - id: repro - attributes: - label: Steps to reproduce - description: Step-by-step instructions to reproduce the behavior. - placeholder: | - 1. Open Buzz and navigate to ... - 2. Click ... - 3. See error - validations: - required: true - - - type: textarea - id: expected - attributes: - label: Expected behavior - description: What did you expect to happen? - validations: - required: true - - - type: dropdown - id: os - attributes: - label: Operating system - options: - - macOS - - Linux - - Windows - - iOS - - Android - - Other - validations: - required: true - - - type: input - id: version - attributes: - label: Buzz version - description: "Find this at the bottom of the Settings sidebar (Desktop). Write \"unknown\" if you can't determine it." - placeholder: "e.g. 0.4.2 or unknown" - validations: - required: true - - - type: textarea - id: logs - attributes: - label: Logs / error output - description: Paste any relevant logs or error messages here. - render: shell - - - type: textarea - id: additional - attributes: - label: Additional context - description: Screenshots, screen recordings, or anything else that helps explain the problem. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ba13e0cec..0086358db1 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1 @@ -blank_issues_enabled: false +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000000..ba5132f0e3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,21 @@ +--- +name: Feature request +about: Propose a new feature or improvement +labels: enhancement +--- + +**Motivation** +What problem does this solve? Who runs into it and when? + +**Proposed solution** +Describe what you'd like to see. + +**Alternatives considered** +What other approaches did you consider? + +**Additional context** +Anything else that helps — links, screenshots, prior art. + +--- + +Before opening: please [search open issues and PRs](https://github.com/block/buzz/issues?q=is%3Aopen) for duplicates — link the closest one, or say "none found". diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml deleted file mode 100644 index d7ad3e46a8..0000000000 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ /dev/null @@ -1,49 +0,0 @@ -name: 💡 Feature Request -description: Propose a new feature or improvement -title: "[Feature] " -labels: [enhancement] -body: - - type: markdown - attributes: - value: | - Before opening a feature request, please [search open issues and PRs](https://github.com/block/buzz/issues?q=is%3Aopen) — someone may have already proposed or started work on the same idea. - - Opening an issue first (before a PR) is strongly recommended for new features — it's the best way to avoid spending a weekend on something someone else is already building. - - - type: input - id: existing - attributes: - label: Closest existing issue or PR - description: "What's the most similar open issue or PR you found? Write the number, or \"none found\"." - placeholder: "#1234 or none found" - validations: - required: true - - - type: textarea - id: problem - attributes: - label: Problem statement - description: What problem does this solve? Who runs into it and when? - placeholder: "As a [user type], I often need to [do X] but currently have to [workaround Y], which is frustrating because..." - validations: - required: true - - - type: textarea - id: solution - attributes: - label: Proposed solution - description: Describe what you'd like to see. Concrete examples, mockups, or API sketches are very helpful. - validations: - required: true - - - type: textarea - id: alternatives - attributes: - label: Alternatives considered - description: What other approaches did you consider? Why do you prefer this one? - - - type: textarea - id: additional - attributes: - label: Additional context - description: Links, screenshots, prior art in other tools, or anything else that helps. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml deleted file mode 100644 index 2c75b1880a..0000000000 --- a/.github/ISSUE_TEMPLATE/question.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: ❓ Question -description: Ask a question about using or contributing to Buzz -title: "[Question] " -labels: [question] -body: - - type: markdown - attributes: - value: | - Have a question? We're happy to help. Please check the [README](https://github.com/block/buzz#readme), [CONTRIBUTING.md](https://github.com/block/buzz/blob/main/CONTRIBUTING.md), and [open issues](https://github.com/block/buzz/issues) first — your answer may already be there. - - - type: textarea - id: question - attributes: - label: What are you trying to do? - description: Describe what you're trying to accomplish or understand. - placeholder: "I'm trying to..." - validations: - required: true - - - type: textarea - id: tried - attributes: - label: What have you tried or looked at? - description: Share what you've already attempted or where you've looked. This helps us give a more targeted answer. - placeholder: "I looked at... / I tried... but..." - validations: - required: true - - - type: input - id: environment - attributes: - label: Environment (optional) - description: OS, Buzz version, or other relevant context. - placeholder: "e.g. macOS 14, Buzz 0.4.2" diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b631f08d0a..325a485102 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,27 +1,8 @@ - +## Summary + -## What does this PR do? +### Related issue + - - -## Related issue - - - -Related issue: - -## Checklist - -- [ ] I searched [open PRs](https://github.com/block/buzz/pulls) and [issues](https://github.com/block/buzz/issues) for duplicates — closest existing: -- [ ] `just ci` passes locally -- [ ] Relevant integration tests pass (`just test`) — required for relay, database, or auth changes -- [ ] This PR contains one logical change (separate unrelated changes into separate PRs) -- [ ] New behavior has tests; bug fixes include a regression test -- [ ] Docs updated if this adds or changes a public API, event kind, MCP tool, or config variable - -## AI / agent assistance - - +### Testing + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a69fc3a22..565d740129 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Welcome, and thank you for your interest in contributing! Buzz is an open-source project and we're glad you're here. This guide will help you get from zero to a merged pull request. -If you have questions that aren't answered here, [open a question issue](https://github.com/block/buzz/issues/new?template=question.yml). +If you have questions that aren't answered here, [open an issue](https://github.com/block/buzz/issues/new). --- @@ -35,52 +35,15 @@ unacceptable behavior to **conduct@buzz-relay.org**. ## Before You Open a PR -A two-minute search can save you from building something that's already in -review. Since launch we've had several people independently build the same -fix — a quick look at open PRs and issues first makes everyone's time count. +Before starting, search [open PRs](https://github.com/block/buzz/pulls) and [open issues](https://github.com/block/buzz/issues) for duplicates — someone may already be working on the same thing. When you open your PR, link the closest existing one in the description (or say "none found"). -### Check for duplicates first +For anything beyond a small fix, opening an issue first is strongly recommended. Describe the problem and proposed solution so a maintainer can acknowledge the approach before you build — it avoids two people building the same thing in parallel. -Search [open PRs](https://github.com/block/buzz/pulls) and -[open issues](https://github.com/block/buzz/issues) before you start. -When you open your PR, name the closest existing one in the description -(or "none found"). When two PRs address the same thing, we keep the earlier -one unless the later one is clearly more complete, and close the other with -a pointer. +Buzz is an agent platform, so AI-assisted PRs are welcome. No need to disclose the tools you used, but you own and must have reviewed the final code. Submissions that are clearly unreviewed may be closed with a pointer here. -### Features: open an issue first (strongly recommended) +We squash-merge, so your PR title becomes the commit subject in `main`. Use [Conventional Commits](https://www.conventionalcommits.org/) format: `feat(mcp): add get_feed_actions tool`. The type prefix (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`) is required. See the [Commit Messages](#commit-messages) section for the full reference. -For anything beyond a typo fix, doc improvement, or obvious bug, opening -an issue first is the best way to avoid spending a weekend on something -someone else is already building. Describe the problem and proposed -solution, and comment to claim it once a maintainer has acknowledged the -approach — that way two people don't build the same thing in parallel. - -Small fixes (typos, doc improvements, obvious bugs with clear fixes) can -go straight to a PR. - -### AI / agent-assisted contributions - -Buzz is an agent platform — AI-assisted PRs are welcome and encouraged. -The **human submitter is accountable**: you personally verified the change -builds and behaves as described, you searched for duplicates, and you will -respond to review feedback. PRs that don't meet this bar may be closed -with a pointer to this section. - -### PR titles follow Conventional Commits - -We squash-merge, so your PR title becomes the commit subject in `main`. -Follow the same format as commit messages: - -``` -feat(mcp): add get_feed_actions tool -fix(auth): reject expired NIP-42 challenges -docs(contributing): add duplicate-check policy -``` - -The type prefix (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`) is -required. See the [Commit Messages](#commit-messages) section for the -full reference. +We review as capacity allows — focused PRs that follow this guide move fastest. ---