From da4b3ee43578fb9ec22ac27aec23ad0369dc6d47 Mon Sep 17 00:00:00 2001 From: Aakash Kattelu Date: Mon, 24 Aug 2026 16:26:00 -0400 Subject: [PATCH] chore: update issue templates and docs (#1032) * chore: update issue templates and docs * chore: slim bug/quality forms and add integration template Drop high-friction required fields from bug and quality issue forms. Add an integration-request form (app stores, plugins, frameworks) labeled integration, and point contributing docs at it. * chore: route security mail to support@ and polish docs intake Use support@honcho.dev for private vulnerability email. List the documentation template in contributing guides, rename Media prove, and add public-issue redaction/security redirects on the docs form. * fix: address render issue in templates and add version field --------- Co-authored-by: Vineeth Voruganti <13438633+VVoruganti@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/1-bug-report.md | 76 --------------- .github/ISSUE_TEMPLATE/1-bug-report.yml | 72 ++++++++++++++ .github/ISSUE_TEMPLATE/2-failing-test.md | 38 -------- .github/ISSUE_TEMPLATE/2-quality-report.yml | 87 +++++++++++++++++ .github/ISSUE_TEMPLATE/3-feature-request.yml | 58 ++++++++++++ .github/ISSUE_TEMPLATE/4-feature-request.md | 42 --------- .../ISSUE_TEMPLATE/4-integration-request.yml | 70 ++++++++++++++ .../{3-docs-bug.md => 5-docs-bug.md} | 10 +- .../ISSUE_TEMPLATE/5-enhancement-request.md | 42 --------- .github/ISSUE_TEMPLATE/6-security-report.md | 93 ------------------- .github/ISSUE_TEMPLATE/7-question-support.md | 25 ----- .github/ISSUE_TEMPLATE/config.yml | 11 +++ CONTRIBUTING.md | 16 ++-- SECURITY.md | 31 +++++++ docs/v2/contributing/guidelines.mdx | 16 ++-- docs/v3/contributing/guidelines.mdx | 16 ++-- 16 files changed, 366 insertions(+), 337 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/1-bug-report.md create mode 100644 .github/ISSUE_TEMPLATE/1-bug-report.yml delete mode 100644 .github/ISSUE_TEMPLATE/2-failing-test.md create mode 100644 .github/ISSUE_TEMPLATE/2-quality-report.yml create mode 100644 .github/ISSUE_TEMPLATE/3-feature-request.yml delete mode 100644 .github/ISSUE_TEMPLATE/4-feature-request.md create mode 100644 .github/ISSUE_TEMPLATE/4-integration-request.yml rename .github/ISSUE_TEMPLATE/{3-docs-bug.md => 5-docs-bug.md} (73%) delete mode 100644 .github/ISSUE_TEMPLATE/5-enhancement-request.md delete mode 100644 .github/ISSUE_TEMPLATE/6-security-report.md delete mode 100644 .github/ISSUE_TEMPLATE/7-question-support.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.md b/.github/ISSUE_TEMPLATE/1-bug-report.md deleted file mode 100644 index 22a18fcb..00000000 --- a/.github/ISSUE_TEMPLATE/1-bug-report.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: "🐞 Bug Report" -about: "Report an issue to help the project improve." -title: "[Bug] " -labels: "bug" -assignees: "" - ---- - -# **🐞 Bug Report** - -## **Describe the bug** - - -* - ---- - -### **Is this a regression?** - - - ---- - -### **To Reproduce** - - - - - -1. -2. -3. -4. - ---- - -### **Expected behaviour** - - -* - ---- - -### **Media prove** - - ---- - -### **Your environment** - - - -* OS: -* Browser name and version: -* Honcho Server Version: -* Honcho Client Version: - ---- - -### **Additional context** - - -* - - diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.yml b/.github/ISSUE_TEMPLATE/1-bug-report.yml new file mode 100644 index 00000000..38373789 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml @@ -0,0 +1,72 @@ +name: Bug report +description: Something is broken or incorrect in Honcho (API, deriver, SDK, managed offering, etc.). +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for filing a bug. Please search [existing issues](https://github.com/plastic-labs/honcho/issues) first. + + **Security vulnerability?** Do not use this form β€” report privately via [SECURITY.md](https://github.com/plastic-labs/honcho/blob/main/SECURITY.md). + + **Memory / recall quality** (wrong or noisy conclusions, weak dialectic answers) with no crash? Prefer the **Memory / recall quality** template. + + - type: dropdown + id: deploy_mode + attributes: + label: Deploy mode + description: Where are you running Honcho? + options: + - Managed (api.honcho.dev / app.honcho.dev) + - Self-hosted + - Unsure + validations: + required: true + + - type: input + id: version + attributes: + label: Honcho version + description: Server image tag or release, and SDK version if you use one. Write "managed" if you are not self-hosting. + placeholder: e.g. server v2.4.1, honcho-ai 2.1.0 + validations: + required: true + + - type: textarea + id: description + attributes: + label: Describe the bug + description: Clear and concise description of what is wrong. + placeholder: When I…, Honcho… + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Minimal steps or a short script/API sequence. Redact secrets, JWTs, and production user content. + placeholder: | + 1. Create a session with … + 2. POST /v3/... with body … + 3. Observe … + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs and evidence + description: Relevant API or deriver logs or stack traces. Redact secrets and user content. + render: shell + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Config knobs, deployment notes, screenshots, related issues/PRs. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/2-failing-test.md b/.github/ISSUE_TEMPLATE/2-failing-test.md deleted file mode 100644 index fed65816..00000000 --- a/.github/ISSUE_TEMPLATE/2-failing-test.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: "πŸ’‰ Failing Test" -about: "Report failing tests or CI jobs." -title: "[Test] " -labels: "Type: Test" -assignees: "" - ---- - -# **πŸ’‰ Failing Test** - -## **Which jobs/test(s) are failing** - - -* - ---- - -## **Reason for failure/description** - - ---- - -### **Media prove** - - ---- - -### **Additional context** - - -* - - diff --git a/.github/ISSUE_TEMPLATE/2-quality-report.yml b/.github/ISSUE_TEMPLATE/2-quality-report.yml new file mode 100644 index 00000000..2a2858a0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-quality-report.yml @@ -0,0 +1,87 @@ +name: Memory / recall quality +description: Conclusions, representations, or dialectic answers are wrong, noisy, missing, or low-quality β€” not a hard crash. +title: "[Quality] " +labels: ["quality"] +body: + - type: markdown + attributes: + value: | + Use this when Honcho runs without erroring, but **memory formation or recall quality** is off (bad conclusions, missed facts, weak chat answers, polluted representations, etc.). + + For crashes, 5xxs, auth failures, or incorrect API mechanics, use the **Bug report** template instead. + + **Do not paste production user content, full peer representations, or secrets.** Redact or invent a minimal synthetic example. + + - type: dropdown + id: deploy_mode + attributes: + label: Deploy mode + options: + - Managed (api.honcho.dev / app.honcho.dev) + - Self-hosted + - Unsure + validations: + required: true + + - type: input + id: version + attributes: + label: Honcho version + description: Server image tag or release, and SDK version if you use one. Write "managed" if you are not self-hosting. + placeholder: e.g. server v2.4.1, honcho-ai 2.1.0 + validations: + required: true + + - type: textarea + id: description + attributes: + label: What is wrong with the quality? + description: Describe the failure mode (noise, omission, contradiction, staleness, over/under-generalization, etc.). + placeholder: After ingesting messages about X, Honcho concludes Y / chat answers Z… + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Minimal scenario + description: > + Smallest synthetic message sequence or setup that triggers the issue. + Prefer invented names/facts over real user data. Include observer/observed + peer setup if relevant (self vs cross-peer). + placeholder: | + 1. Peers: alice (user), bot (agent); session S + 2. Messages ingested: … + 3. Query / conclusion listing shows: … + validations: + required: true + + - type: textarea + id: config + attributes: + label: Relevant config + description: > + Custom instructions, provider/model, deriver/dream settings, or workspace/peer + config that affects reasoning. Redact secrets. + placeholder: | + Provider/model: … + Custom instructions: (summary or redacted) + Other: … + validations: + required: false + + - type: textarea + id: evidence + attributes: + label: Evidence + description: Redacted conclusion text, chat excerpts, or counts that show the failure. No production PII. + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Frequency, scale (message/conclusion counts), related issues, workarounds. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/3-feature-request.yml b/.github/ISSUE_TEMPLATE/3-feature-request.yml new file mode 100644 index 00000000..f0d935ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-feature-request.yml @@ -0,0 +1,58 @@ +name: Feature request +description: Propose a new capability or an improvement to an existing one. +title: "[Feature] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Tell us what problem you are trying to solve. Concrete use cases beat abstract wishlists. + + Questions about how to use Honcho belong on [Discord](https://discord.gg/honcho), not here. + + - type: dropdown + id: request_type + attributes: + label: Request type + options: + - New capability + - Improve an existing capability + - API / SDK surface + - Managed offering + - Docs / DX + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem + description: What is hard or impossible today? Who hits this? + placeholder: I'm always frustrated when… / My integration needs… + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: What you would like Honcho to support. Sketches and API shapes welcome. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Workarounds, other APIs, or designs you already tried or ruled out. + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Links, prior art, screenshots, related issues/PRs. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/4-feature-request.md b/.github/ISSUE_TEMPLATE/4-feature-request.md deleted file mode 100644 index 00400dca..00000000 --- a/.github/ISSUE_TEMPLATE/4-feature-request.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: "πŸš€πŸ†• Feature Request" -about: "Suggest an idea or possible new feature for this project." -title: "" -labels: 'feature' -assignees: '' - ---- - -# **πŸš€ Feature Request** - -## **Is your feature request related to a problem? Please describe.** - - -* - ---- - -## **Describe the solution you'd like** - - -* - ---- - -## **Describe alternatives you've considered** - - -* - ---- - -### **Additional context** - - -* - - diff --git a/.github/ISSUE_TEMPLATE/4-integration-request.yml b/.github/ISSUE_TEMPLATE/4-integration-request.yml new file mode 100644 index 00000000..a3a45db4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/4-integration-request.yml @@ -0,0 +1,70 @@ +name: Integration request +description: Add Honcho to an app store, agent framework, plugin marketplace, or other third-party surface β€” or improve an existing integration. +title: "[Integration] " +labels: ["integration"] +body: + - type: markdown + attributes: + value: | + Use this when you want Honcho available in (or better supported by) an external product surface β€” app stores, agent frameworks, plugin marketplaces, IDE extensions, MCP clients, etc. + + For core API/SDK product features that are not about a third-party surface, use the **Feature request** template instead. + + - type: dropdown + id: request_kind + attributes: + label: What kind of request is this? + options: + - New integration / listing (Honcho is not there yet) + - Improve an existing integration + - Official plugin / extension + - Marketplace or app-store listing + - Docs / guide for integrating with a specific tool + - Other + validations: + required: true + + - type: input + id: target + attributes: + label: Target product or platform + description: Name of the app, framework, marketplace, or tool. + placeholder: e.g. Claude Code, Cursor, CrewAI, OpenClaw, VS Code Marketplace… + validations: + required: true + + - type: input + id: target_url + attributes: + label: Link (if any) + description: Docs, marketplace page, repo, or product URL. + placeholder: https://… + validations: + required: false + + - type: textarea + id: why + attributes: + label: Why does this matter? + description: Who would use it, and what does the integration unlock? + validations: + required: true + + - type: textarea + id: shape + attributes: + label: What should the integration look like? + description: > + e.g. one-click install, MCP server listing, native memory backend, + SDK recipe, plugin with slash commands, env-var setup, etc. + Link to prior art or a sketch if you have one. + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Related issues, community demand, constraints, offers to help build it. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/3-docs-bug.md b/.github/ISSUE_TEMPLATE/5-docs-bug.md similarity index 73% rename from .github/ISSUE_TEMPLATE/3-docs-bug.md rename to .github/ISSUE_TEMPLATE/5-docs-bug.md index 7693d543..1169ff15 100644 --- a/.github/ISSUE_TEMPLATE/3-docs-bug.md +++ b/.github/ISSUE_TEMPLATE/5-docs-bug.md @@ -8,6 +8,10 @@ assignees: "" --- # **πŸ“š Documentation Issue Report** +**Security vulnerability?** Do not use this form β€” report privately via [SECURITY.md](https://github.com/plastic-labs/honcho/blob/main/SECURITY.md). + +GitHub issues are public. Redact secrets, JWTs, and production user content. + ## **Describe the bug** @@ -33,8 +37,8 @@ assignees: "" --- -### **Media prove** - +### **Screenshots and videos** + --- @@ -46,7 +50,7 @@ assignees: "" --- ### **Additional context** - + * diff --git a/.github/ISSUE_TEMPLATE/5-enhancement-request.md b/.github/ISSUE_TEMPLATE/5-enhancement-request.md deleted file mode 100644 index d75f8756..00000000 --- a/.github/ISSUE_TEMPLATE/5-enhancement-request.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: "πŸš€βž• Enhancement Request" -about: "Suggest an enhancement for this project. Improve an existing feature" -title: "" -labels: "Type: Enhancement" -assignees: "" - ---- - -# **πŸš€ Enhancement Request** - -## **Is your enhancement request related to a problem? Please describe.** - - -* - ---- - -## **Describe the solution you'd like** - - -* - ---- - -## **Describe alternatives you've considered** - - -* - ---- - -### **Additional context** - - -* - - diff --git a/.github/ISSUE_TEMPLATE/6-security-report.md b/.github/ISSUE_TEMPLATE/6-security-report.md deleted file mode 100644 index 213f64c6..00000000 --- a/.github/ISSUE_TEMPLATE/6-security-report.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: "⚠️ Security Report" -about: "Report an issue to help the project improve." -title: "" -labels: "security" -assignees: "" - ---- - - - -# **⚠️ Security Report** - -## **Describe the security issue** - - -* - ---- - -### **To Reproduce** - - - - - -1. -2. -3. -4. - ---- - -### **Expected behaviour** - - -* - ---- - -### **Media prove** - - ---- - -### **Your environment** - - - -* OS: -* Browser name and version: -* Honcho Server Version: -* Honcho Client Version: - ---- - -### **Additional context** - - -* diff --git a/.github/ISSUE_TEMPLATE/7-question-support.md b/.github/ISSUE_TEMPLATE/7-question-support.md deleted file mode 100644 index 894359f4..00000000 --- a/.github/ISSUE_TEMPLATE/7-question-support.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: "❓ Question or Support Request" -about: "Questions and requests for support." -title: "" -labels: "question" -assignees: "" - ---- - -# **❓ Question or Support Request** - -## **Describe your question or ask for support.** - - -* - - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..237b4532 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Report a security vulnerability + url: https://github.com/plastic-labs/honcho/security/advisories/new + about: Private vulnerability reporting only β€” do not file public security issues. + - name: Question or support + url: https://discord.gg/honcho + about: Ask the community and maintainers on Discord. + - name: Documentation + url: https://honcho.dev/docs + about: Guides, API reference, and self-hosting docs. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f0f44b5..23eb7c58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -196,17 +196,21 @@ We welcome various types of contributions: When reporting bugs or requesting features: 1. Check if the issue already exists -2. Use the appropriate issue template +2. Use the appropriate [issue template](https://github.com/plastic-labs/honcho/issues/new/choose) (bug, memory/recall quality, feature, integration, or documentation) 3. Provide clear reproduction steps for bugs -4. Include relevant environment information +4. Include relevant environment information (managed vs self-hosted, server version, SDK) 5. Be specific about expected vs actual behavior +6. Redact secrets, JWTs, and production user content ## Questions and Support -- **General questions** - Join our [Discord](http://discord.gg/honcho) -- **Bug reports** - Use GitHub issues -- **Feature requests** - Use GitHub issues with the feature request template -- **Security issues** - Please email us privately rather than opening a public issue +- **General questions** - Join our [Discord](https://discord.gg/honcho) +- **Bug reports** - GitHub issues β†’ Bug report template +- **Memory / recall quality** - GitHub issues β†’ Memory / recall quality template +- **Feature requests** - GitHub issues β†’ Feature request template +- **Integrations / plugins / app-store listings** - GitHub issues β†’ Integration request template +- **Documentation issues** - GitHub issues β†’ Documentation issue template +- **Security issues** - Report **privately** only β€” see [`SECURITY.md`](./SECURITY.md) (GitHub Private Vulnerability Reporting or email). Do not open a public issue. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..172758d3 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,31 @@ +# Security Policy + +## Reporting a vulnerability + +**Do not file a public GitHub issue for security vulnerabilities.** + +Please report security issues privately using one of: + +1. **[GitHub Private Vulnerability Reporting](https://github.com/plastic-labs/honcho/security/advisories/new)** (preferred) +2. Email **** with subject line `[SECURITY] …` + +Include as much of the following as you can: + +- Description of the issue and its impact +- Steps to reproduce, or a proof of concept +- Affected component (API, deriver, auth/JWT, SDK, managed offering, etc.) +- Honcho version or image tag, and whether you are on managed or self-hosted + +Honcho stores conversational data and peer representations. **Do not** attach production user content, API keys, JWTs, or other secrets to a report unless we explicitly ask for a redacted sample. + +## What to expect + +We will acknowledge valid reports as soon as we can and will keep you updated on remediation status. Please give us a reasonable window to investigate and fix before any public disclosure. + +## Supported versions + +Security fixes are applied to the latest release on `main` and, when practical, to the most recent tagged release line. Older versions may not receive backports. + +## Non-security bugs + +For ordinary bugs, memory/recall quality issues, and feature requests, use the [issue templates](https://github.com/plastic-labs/honcho/issues/new/choose). diff --git a/docs/v2/contributing/guidelines.mdx b/docs/v2/contributing/guidelines.mdx index 398a8b09..12f44179 100644 --- a/docs/v2/contributing/guidelines.mdx +++ b/docs/v2/contributing/guidelines.mdx @@ -153,17 +153,21 @@ We welcome various types of contributions: When reporting bugs or requesting features: 1. Check if the issue already exists -2. Use the appropriate issue template +2. Use the appropriate [issue template](https://github.com/plastic-labs/honcho/issues/new/choose) (bug, memory/recall quality, feature, integration, or documentation) 3. Provide clear reproduction steps for bugs -4. Include relevant environment information +4. Include relevant environment information (managed vs self-hosted, server version, SDK) 5. Be specific about expected vs actual behavior +6. Redact secrets, JWTs, and production user content ## Questions and Support -- **General questions** - Join our [Discord](http://discord.gg/honcho) -- **Bug reports** - Use GitHub issues -- **Feature requests** - Use GitHub issues with the feature request template -- **Security issues** - Please email us privately rather than opening a public issue +- **General questions** - Join our [Discord](https://discord.gg/honcho) +- **Bug reports** - GitHub issues β†’ Bug report template +- **Memory / recall quality** - GitHub issues β†’ Memory / recall quality template +- **Feature requests** - GitHub issues β†’ Feature request template +- **Integrations / plugins / app-store listings** - GitHub issues β†’ Integration request template +- **Documentation issues** - GitHub issues β†’ Documentation issue template +- **Security issues** - Report **privately** only β€” see [`SECURITY.md`](https://github.com/plastic-labs/honcho/blob/main/SECURITY.md) (GitHub Private Vulnerability Reporting or email). Do not open a public issue. ## License diff --git a/docs/v3/contributing/guidelines.mdx b/docs/v3/contributing/guidelines.mdx index 398a8b09..12f44179 100644 --- a/docs/v3/contributing/guidelines.mdx +++ b/docs/v3/contributing/guidelines.mdx @@ -153,17 +153,21 @@ We welcome various types of contributions: When reporting bugs or requesting features: 1. Check if the issue already exists -2. Use the appropriate issue template +2. Use the appropriate [issue template](https://github.com/plastic-labs/honcho/issues/new/choose) (bug, memory/recall quality, feature, integration, or documentation) 3. Provide clear reproduction steps for bugs -4. Include relevant environment information +4. Include relevant environment information (managed vs self-hosted, server version, SDK) 5. Be specific about expected vs actual behavior +6. Redact secrets, JWTs, and production user content ## Questions and Support -- **General questions** - Join our [Discord](http://discord.gg/honcho) -- **Bug reports** - Use GitHub issues -- **Feature requests** - Use GitHub issues with the feature request template -- **Security issues** - Please email us privately rather than opening a public issue +- **General questions** - Join our [Discord](https://discord.gg/honcho) +- **Bug reports** - GitHub issues β†’ Bug report template +- **Memory / recall quality** - GitHub issues β†’ Memory / recall quality template +- **Feature requests** - GitHub issues β†’ Feature request template +- **Integrations / plugins / app-store listings** - GitHub issues β†’ Integration request template +- **Documentation issues** - GitHub issues β†’ Documentation issue template +- **Security issues** - Report **privately** only β€” see [`SECURITY.md`](https://github.com/plastic-labs/honcho/blob/main/SECURITY.md) (GitHub Private Vulnerability Reporting or email). Do not open a public issue. ## License