From cc449639242d53f843cfc974a2b4c9f0c860d667 Mon Sep 17 00:00:00 2001 From: Aakash Kattelu Date: Tue, 18 Aug 2026 09:33:03 -0400 Subject: [PATCH] chore: update issue templates and docs --- .github/ISSUE_TEMPLATE/1-bug-report.md | 76 ---------- .github/ISSUE_TEMPLATE/1-bug-report.yml | 139 ++++++++++++++++++ .github/ISSUE_TEMPLATE/2-failing-test.md | 38 ----- .github/ISSUE_TEMPLATE/2-quality-report.yml | 128 ++++++++++++++++ .github/ISSUE_TEMPLATE/3-feature-request.yml | 58 ++++++++ .../{3-docs-bug.md => 4-docs-bug.md} | 0 .github/ISSUE_TEMPLATE/4-feature-request.md | 42 ------ .../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 | 14 +- SECURITY.md | 31 ++++ docs/v2/contributing/guidelines.mdx | 14 +- docs/v3/contributing/guidelines.mdx | 14 +- 15 files changed, 391 insertions(+), 334 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 rename .github/ISSUE_TEMPLATE/{3-docs-bug.md => 4-docs-bug.md} (100%) delete mode 100644 .github/ISSUE_TEMPLATE/4-feature-request.md 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..af080c96 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml @@ -0,0 +1,139 @@ +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: dropdown + id: component + attributes: + label: Component + description: Where does the bug show up? + options: + - API / HTTP routes + - Deriver / queue / message processing + - Dreamer / consolidation + - Dialectic / chat endpoint + - Summarizer / session context + - Auth / JWT / API keys + - Embeddings / vector search + - Python SDK + - TypeScript SDK + - CLI + - Managed offering (dashboard, billing, hosted infra) + - Docs + - Other + validations: + required: true + + - type: input + id: server_version + attributes: + label: Honcho server version + description: Image tag, PyPI/git revision, or release (e.g. `v2.4.1`, `main@abc1234`, Docker digest). + placeholder: e.g. v2.4.1 + validations: + required: true + + - type: input + id: sdk_version + attributes: + label: SDK / client version (if applicable) + description: Python `honcho-ai` or TypeScript `@honcho-ai/sdk` version, or "n/a". + placeholder: e.g. honcho-ai 1.2.0 / n/a + validations: + required: false + + - 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 … + render: markdown + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What you expected to happen. + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What actually happened (error messages, status codes, incorrect data). + validations: + required: true + + - type: dropdown + id: regression + attributes: + label: Is this a regression? + options: + - "No" + - "Yes β€” it worked in an earlier version" + - Unsure + validations: + required: true + + - type: input + id: last_good_version + attributes: + label: Last known good version (if regression) + placeholder: e.g. v2.3.0 + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Logs and evidence + description: Relevant API or deriver logs, stack traces, or screenshots. Redact secrets and user content. + render: shell + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Config knobs (provider, deriver/dream settings), deployment notes, 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..4a0840d2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-quality-report.yml @@ -0,0 +1,128 @@ +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: dropdown + id: surface + attributes: + label: Which surface looks wrong? + description: Pick the closest match; add detail below if several apply. + options: + - Conclusions (extracted memory) + - Dialectic / chat answers + - Peer representation / peer card + - Session context / summaries + - Search (messages or conclusions) + - Dreamer consolidation / reasoning + - Other + validations: + required: true + + - type: input + id: server_version + attributes: + label: Honcho server version + description: Image tag, revision, or release. + placeholder: e.g. v2.4.1 + 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: expected + attributes: + label: What should have happened instead? + description: Ideal conclusions, answer, or representation behavior. + 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: … + render: markdown + validations: + required: true + + - type: dropdown + id: reasoning_level + attributes: + label: Dialectic reasoning level (if chat-related) + options: + - n/a β€” not chat-related + - minimal + - low + - medium + - high + - max + - Unsure / default + 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. + render: markdown + 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/3-docs-bug.md b/.github/ISSUE_TEMPLATE/4-docs-bug.md similarity index 100% rename from .github/ISSUE_TEMPLATE/3-docs-bug.md rename to .github/ISSUE_TEMPLATE/4-docs-bug.md 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/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..52418e05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -196,17 +196,19 @@ 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, or feature) 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 +- **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..64f7e2a0 --- /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..d14bf518 100644 --- a/docs/v2/contributing/guidelines.mdx +++ b/docs/v2/contributing/guidelines.mdx @@ -153,17 +153,19 @@ 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, or feature) 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 +- **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..d14bf518 100644 --- a/docs/v3/contributing/guidelines.mdx +++ b/docs/v3/contributing/guidelines.mdx @@ -153,17 +153,19 @@ 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, or feature) 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 +- **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