From ae67e1e8adc6632db5ccaa8fd0b102be798a5152 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Mon, 8 Jun 2026 20:44:28 +0200 Subject: [PATCH] docs(github): refresh issue/PR templates and CONTRIBUTING for the AfterTouch toolkit (refs #478) The templates were written during the Go-library era and no longer match the project: they asked reporters (mostly speaker owners) for Go versions, library versions, pkg/client pickers, and minimal repro code, while pointing at dead doc links. #478 reported one of those dead links (the troubleshooting guide). Issue templates: - Fix the dead troubleshooting + API-cookbook links (now the published docs site). - Delete the legacy .md duplicates of bug_report/feature_request/device_compatibility (GitHub was showing them alongside the .yml forms). - Rewrite bug_report.yml and feature_request.yml around how people actually run AfterTouch (service/CLI/player/backup); make them short and easy to file, with the encrypted diagnostic export as the headline ask. - Add device_compatibility.yml (slim) and a config.yml chooser that links Discussions, the Survival Guide, and the Troubleshooting Guide. Blank issues stay enabled. Diagnostic-export transparency: instead of claiming the report "contains no readable secrets", state honestly that the raw datastore XML (e.g. Sources.xml) is included as-is and can carry access tokens for linked services (Spotify/Amazon), that there is no datastore-redaction setting, and that users can unlink first or send privately. Point at the same support email the Health tab shows (aftertouch-support@gesellix.net) and note GitHub blocks .age uploads (rename to .age.txt or zip). PR template: cut the library-era ceremony down to summary/issue/type/testing/ checklist, add an "AI-assisted contributions" note (agent code welcome, unreviewed slop rejected), a no-personal-data reminder, and an MIT + Code of Conduct footer. CONTRIBUTING.md: reframe from "Bose SoundTouch API Client / Go library" to the AfterTouch toolkit; fix build paths (./build/) and make targets; drop broken references; point at CLAUDE.md; add the AI stance and the no-personal-data rule. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.md | 77 --- .github/ISSUE_TEMPLATE/bug_report.yml | 223 +++---- .github/ISSUE_TEMPLATE/config.yml | 12 + .../ISSUE_TEMPLATE/device_compatibility.md | 113 ---- .../ISSUE_TEMPLATE/device_compatibility.yml | 74 +++ .github/ISSUE_TEMPLATE/feature_request.md | 77 --- .github/ISSUE_TEMPLATE/feature_request.yml | 205 ++----- .github/pull_request_template.md | 190 +----- CONTRIBUTING.md | 571 ++++-------------- 9 files changed, 354 insertions(+), 1188 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/device_compatibility.md create mode 100644 .github/ISSUE_TEMPLATE/device_compatibility.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 70e5516..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: 'bug' -assignees: '' - ---- - -**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. - -**Environment (please complete the following information):** -- OS: [e.g. macOS 14.0, Windows 11, Ubuntu 22.04] -- Go version: [e.g. 1.25.5] -- Library version: [e.g. v1.0.0, commit hash if using main branch] -- SoundTouch device model: [e.g. SoundTouch 10, SoundTouch 20] -- Device firmware version: [if known] - -**Command/Code that failed** -```bash -# If using CLI tool, provide the exact command -soundtouch-cli --host 192.0.2.100 info get - -# If using Go library, provide minimal code example -``` - -**Error output** -``` -Paste the complete error message here, including stack traces if available -``` - -**Device Information (if applicable)** -```xml - - -``` - -**Network Configuration** -- Network setup: [e.g. home WiFi, corporate network, VPN] -- Firewall/proxy: [any network restrictions] -- Device connectivity: [how device connects to network - WiFi, Ethernet] - -**Additional context** -Add any other context about the problem here. For example: -- Does this happen consistently or intermittently? -- Did this work in a previous version? -- Are there any workarounds? -- Any relevant log files or debug output - -**Logs (if applicable)** -``` -# Enable verbose logging with --verbose flag or debug environment variable -# and paste relevant log output here -``` - -**Screenshots** -If applicable, add screenshots to help explain your problem. - ---- - -**Checklist** -- [ ] I have searched existing issues to avoid duplicates -- [ ] I have tested with the latest version -- [ ] I have included all relevant environment information -- [ ] I have provided a minimal reproduction case -- [ ] I have included complete error messages \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index f458c48..a2b1c19 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,201 +1,118 @@ name: Bug Report -description: File a bug report to help us improve the library +description: Something in AfterTouch isn't working the way it should title: "[Bug]: " labels: ["bug", "triage"] -assignees: [] body: - type: markdown attributes: value: | - Thanks for taking the time to fill out this bug report! Please provide as much detail as possible to help us diagnose and fix the issue. + Thanks for helping improve **AfterTouch**! 🙏 - - type: input - id: version - attributes: - label: Library Version - description: What version of the library are you using? - placeholder: "v1.0.0" - validations: - required: true + AfterTouch is a community-built toolkit that keeps Bose SoundTouch speakers + working after the Bose cloud shutdown. We both give and ask for support here, + so don't worry about getting every field perfect. - - type: dropdown - id: go-version - attributes: - label: Go Version - description: What version of Go are you using? - options: - - "1.25.5+" - - "1.25" - - "1.24" - - "1.23" - - "Other (please specify in description)" - validations: - required: true - - - type: dropdown - id: operating-system - attributes: - label: Operating System - description: What operating system are you running on? - options: - - "Linux" - - "macOS" - - "Windows" - - "FreeBSD" - - "Other (please specify in description)" - validations: - required: true - - - type: input - id: device-model - attributes: - label: Bose Device Model - description: What Bose SoundTouch device are you trying to control? - placeholder: "SoundTouch 10, SoundTouch 20, etc." - validations: - required: true - - - type: input - id: device-firmware - attributes: - label: Device Firmware Version - description: What firmware version is your device running? (Check in Bose app or via /info endpoint) - placeholder: "4.8.1.4567.891234567" + A quick look at the + [Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/) + often saves time. For "how do I...?" questions, please use + [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) instead. - type: textarea id: description attributes: - label: Bug Description - description: A clear and concise description of what the bug is. - placeholder: "Describe what happened and what you expected to happen..." + label: What happened? + description: What went wrong, and what did you expect to happen instead? + placeholder: "When I play a radio station from the player UI, the speaker shows an orange light and nothing plays. I expected it to start playing." validations: required: true - type: textarea - id: reproduction-steps + id: steps attributes: - label: Steps to Reproduce - description: Steps to reproduce the behavior + label: Steps to reproduce + description: How can we trigger it? Rough steps are fine. placeholder: | - 1. Go to '...' - 2. Click on '....' - 3. Scroll down to '....' - 4. See error + 1. Open the player UI + 2. Search for a station + 3. Press play + 4. ... validations: - required: true + required: false - type: textarea - id: expected-behavior + id: diagnostic attributes: - label: Expected Behavior - description: A clear and concise description of what you expected to happen. - placeholder: "What should have happened instead?" + label: Diagnostic report (the most helpful thing you can attach) + description: | + In the AfterTouch **admin UI**, open the **Health tab** and click + **Download diagnostic report**. It is by far the best way to help us + diagnose a bug. GitHub blocks `.age` uploads, so rename the file to + `.age.txt` (or zip it) before dragging it into this box. You can also email + it instead: aftertouch-support@gesellix.net. + + The file is **encrypted** to the maintainer's key, so only the maintainer + can open it. The structured summary has credentials redacted, but the raw + datastore files (for example `Sources.xml`) are included as-is and can + contain the access tokens your speaker uses for linked services like + Spotify or Amazon. If that is a concern, unlink those services before + exporting, or email the report privately instead. + placeholder: "Attach the aftertouch-diagnostic-*.age.txt (or .zip) file here." validations: - required: true + required: false - - type: textarea - id: code-sample + - type: input + id: device attributes: - label: Code Sample - description: Please provide a minimal code sample that reproduces the issue - render: go - placeholder: | - package main + label: Speaker model & firmware + description: Which speaker, and (if you know it) the firmware version. + placeholder: "SoundTouch 10, firmware 27.0.6" + validations: + required: false - import ( - "fmt" - "github.com/gesellix/bose-soundtouch/pkg/client" - ) + - type: dropdown + id: how-run + attributes: + label: How are you running AfterTouch? + options: + - "Docker / docker compose" + - "Prebuilt binary" + - "Built from source" + - "Not sure" + validations: + required: false - func main() { - // Your code that demonstrates the issue - } + - type: input + id: version + attributes: + label: AfterTouch version + description: Shown in the admin UI footer, or via the binary's `--version`. + placeholder: "v0.111.2" validations: required: false - type: textarea id: logs attributes: - label: Error Messages / Logs - description: Please include any relevant error messages, stack traces, or log output + label: Logs / error messages + description: Any relevant output from the service, CLI, or browser console. Please mask real LAN IPs if you can. render: shell - placeholder: | - Error: connection refused - at github.com/gesellix/bose-soundtouch/pkg/client.(*Client).makeRequest - ... - validations: - required: false - - - type: dropdown - id: component - attributes: - label: Component - description: Which component is affected? - multiple: true - options: - - "Client Library (pkg/client)" - - "WebSocket Events" - - "Device Discovery" - - "CLI Tool" - - "Models/XML Parsing" - - "Documentation" - - "Examples" - - "Build/Release" - validations: - required: false - - - type: dropdown - id: severity - attributes: - label: Severity - description: How severe is this bug? - options: - - "Low - Minor inconvenience" - - "Medium - Affects functionality but workaround exists" - - "High - Blocks major functionality" - - "Critical - Application crashes or data loss" - validations: - required: true - - - type: textarea - id: network-info - attributes: - label: Network Configuration - description: Details about your network setup (if relevant to the issue) - placeholder: | - - Device IP: 192.0.2.100 - - Network type: WiFi/Ethernet - - Router model: - - Any firewalls or network restrictions: - validations: - required: false - - - type: textarea - id: additional-context - attributes: - label: Additional Context - description: Add any other context about the problem here - placeholder: "Screenshots, network traces, related issues, etc." validations: required: false - type: checkboxes - id: troubleshooting + id: checklist attributes: - label: Troubleshooting Steps - description: Have you tried these troubleshooting steps? + label: Before you submit options: - - label: "I have checked the [Troubleshooting Guide](docs/TROUBLESHOOTING.md)" - - label: "I have verified my device is reachable (ping test)" - - label: "I have tested with the CLI tool" - - label: "I have checked for similar existing issues" - - label: "I am using the latest version of the library" + - label: "I checked the [Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/)" + - label: "I searched [existing issues](https://github.com/gesellix/Bose-SoundTouch/issues) for a duplicate" + - label: "I'm on a recent AfterTouch version" - type: checkboxes - id: terms + id: coc attributes: label: Code of Conduct - description: By submitting this issue, you agree to follow our Code of Conduct + description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md). options: - label: "I agree to follow this project's Code of Conduct" required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f25fce9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +# Free-form blank issues stay enabled for anything that doesn't fit a template. +blank_issues_enabled: true +contact_links: + - name: 💬 Questions & Support (Discussions) + url: https://github.com/gesellix/Bose-SoundTouch/discussions + about: "\"How do I...?\", setup help, and general support. AfterTouch is a community effort: ask here, and help others when you can." + - name: 🚑 Survival Guide + url: https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/ + about: "Getting your speakers working again after the Bose cloud shutdown. Start here." + - name: 🔧 Troubleshooting Guide + url: https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/ + about: "Common problems and their fixes. Please check this before filing a bug." diff --git a/.github/ISSUE_TEMPLATE/device_compatibility.md b/.github/ISSUE_TEMPLATE/device_compatibility.md deleted file mode 100644 index b09c000..0000000 --- a/.github/ISSUE_TEMPLATE/device_compatibility.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -name: Device compatibility report -about: Report compatibility with a new SoundTouch device model -title: 'Device Compatibility: [Device Model]' -labels: 'compatibility, documentation' -assignees: '' - ---- - -**Device Information** -- **Model**: [e.g. SoundTouch 30, Wave SoundTouch IV, SoundTouch Portable] -- **Model Number**: [e.g. 738102-2100, found on device label] -- **Firmware Version**: [if known, from device settings or API response] -- **Purchase Date**: [approximate, helps identify firmware generation] - -**Testing Results** - -### Basic Functionality -- [ ] Device discovery (UPnP/mDNS) -- [ ] Basic device info (`GET /info`) -- [ ] Now playing status (`GET /now_playing`) -- [ ] Media controls (play/pause/stop) -- [ ] Volume control -- [ ] Source listing (`GET /sources`) - -### Advanced Features -- [ ] Bass control (`GET/POST /bass`) -- [ ] Balance control (`GET/POST /balance`) - if stereo device -- [ ] Clock/time management (`GET/POST /clockTime`) -- [ ] Network information (`GET /networkInfo`) -- [ ] WebSocket events -- [ ] Multiroom zones (master) -- [ ] Multiroom zones (slave) - -### Advanced Audio Controls (Professional/High-end Models) -- [ ] DSP controls (`GET/POST /audiodspcontrols`) -- [ ] Tone controls (`GET/POST /audioproducttonecontrols`) -- [ ] Level controls (`GET/POST /audioproductlevelcontrols`) - -### Known Issues -List any features that don't work or behave unexpectedly: -- Feature name: Description of issue -- Command that fails: `soundtouch-cli command that doesn't work` - -**Device Info Output** -```xml - - -``` - -**Device Capabilities Output** -```xml - - -``` - -**Bass Capabilities (if supported)** -```xml - - -``` - -**Available Sources** -```xml - - -``` - -**Testing Commands Used** -```bash -# List the specific commands you used for testing -soundtouch-cli --host 192.0.2.100 info get -soundtouch-cli --host 192.0.2.100 play start -# ... etc -``` - -**Environment** -- **OS**: [e.g. macOS 14.0, Windows 11, Ubuntu 22.04] -- **Go version**: [e.g. 1.25.5] -- **Library version**: [e.g. v1.0.0, commit hash] -- **Network setup**: [home WiFi, corporate, etc.] - -**Performance Notes** -- Response times: [normal, slow, timeouts] -- Specific timeouts: [any endpoints that timeout] -- WebSocket stability: [connects reliably, frequent disconnects, etc.] - -**Comparison with Tested Models** -If you have experience with other SoundTouch models: -- **Similar to**: [e.g. works like SoundTouch 20] -- **Differences from**: [e.g. missing balance control compared to SoundTouch 30] - -**Additional Notes** -Any other observations about device behavior, quirks, or special considerations: -- Does the device have unique features not seen in other models? -- Are there any setup requirements or configuration notes? -- Does it work differently in different network environments? - -**Documentation Impact** -- [ ] Update supported devices list -- [ ] Add device-specific notes to documentation -- [ ] Update compatibility matrix -- [ ] Add to integration test suite - ---- - -**Checklist** -- [ ] I have tested basic functionality (info, play, volume) -- [ ] I have tested advanced features available on this device -- [ ] I have provided complete device information output -- [ ] I have noted any issues or limitations -- [ ] I have tested in a typical network environment -- [ ] I understand this helps improve compatibility for all users \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/device_compatibility.yml b/.github/ISSUE_TEMPLATE/device_compatibility.yml new file mode 100644 index 0000000..f3d9071 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/device_compatibility.yml @@ -0,0 +1,74 @@ +name: Device Compatibility Report +description: Tell us how AfterTouch works (or doesn't) with your SoundTouch model +title: "[Compatibility]: " +labels: ["compatibility", "documentation"] +body: + - type: markdown + attributes: + value: | + Thanks for helping map out which speakers AfterTouch supports! 📋 + + Reports like yours help everyone with the same model, and feed our + compatibility notes in the docs. + + - type: input + id: model + attributes: + label: Speaker model + placeholder: "SoundTouch 20, Wave SoundTouch IV, SoundTouch Portable, ..." + validations: + required: true + + - type: input + id: firmware + attributes: + label: Firmware version + description: From the admin UI, the Bose app, or the device's `/info`. + placeholder: "27.0.6" + validations: + required: false + + - type: textarea + id: works + attributes: + label: What works? + placeholder: | + - Discovery + - Playback and presets + - Stereo pair / multiroom + - Migration off the Bose cloud + validations: + required: false + + - type: textarea + id: broken + attributes: + label: What doesn't work? + placeholder: "Anything that failed or behaved unexpectedly on this model." + validations: + required: false + + - type: textarea + id: diagnostic + attributes: + label: Diagnostic report + description: | + Optional, but very helpful. In the AfterTouch **admin UI**, open the + **Health tab** and click **Download diagnostic report**. GitHub blocks + `.age` uploads, so rename the file to `.age.txt` (or zip it) before + attaching, or email it to aftertouch-support@gesellix.net. It is encrypted + to the maintainer's key. The raw datastore files inside are included as-is, + so if you have linked services like Spotify or Amazon, unlink them first or + send the file privately. + placeholder: "Attach the aftertouch-diagnostic-*.age.txt (or .zip) file here." + validations: + required: false + + - type: checkboxes + id: coc + attributes: + label: Code of Conduct + description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md). + options: + - label: "I agree to follow this project's Code of Conduct" + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 71acb58..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: 'enhancement' -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Use case** -Describe your specific use case and how this feature would benefit you and other users. - -**SoundTouch API Support** -- [ ] This feature is supported by the official SoundTouch API -- [ ] This feature is NOT supported by the SoundTouch API (custom enhancement) -- [ ] I'm not sure if this is supported by the SoundTouch API - -**API Documentation Reference (if applicable)** -If this feature is based on a SoundTouch API endpoint, please provide: -- Endpoint URL: [e.g. GET /newendpoint] -- Documentation reference: [page number or section in official API docs] -- XML request/response examples: [if known] - -**Implementation Details (optional)** -If you have ideas about how this could be implemented: -- Suggested package/module: [e.g. pkg/client, cmd/soundtouch-cli] -- Method signatures: [if you have suggestions] -- CLI commands: [if this affects the CLI tool] - -**Device Compatibility** -- SoundTouch models this applies to: [e.g. all models, SoundTouch 20+, specific models] -- Have you tested this manually: [e.g. via curl, Postman, etc.] - -**Examples** -Provide examples of how you would like to use this feature: - -```go -// Go library example -client.NewFeature(parameters) -``` - -```bash -# CLI example -soundtouch-cli --host 192.0.2.100 new-feature --param value -``` - -**Priority** -- [ ] Critical - blocks important functionality -- [ ] High - would significantly improve user experience -- [ ] Medium - nice to have enhancement -- [ ] Low - minor improvement - -**Additional context** -Add any other context, screenshots, or examples about the feature request here. - -**Related Issues** -- Related to #[issue number] -- Depends on #[issue number] -- Blocks #[issue number] - ---- - -**Checklist** -- [ ] I have searched existing issues to avoid duplicates -- [ ] I have checked the documentation to ensure this feature doesn't already exist -- [ ] I have provided a clear use case and rationale -- [ ] I have considered the impact on existing functionality -- [ ] I understand this may require SoundTouch API support to implement \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 2ea7bb3..8c34512 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,205 +1,74 @@ name: Feature Request -description: Suggest an idea or enhancement for this project +description: Suggest an idea or improvement for AfterTouch title: "[Feature]: " labels: ["enhancement", "triage"] -assignees: [] body: - type: markdown attributes: value: | - Thanks for suggesting a new feature! Please provide as much detail as possible to help us understand your request and its potential impact. + Thanks for the idea! 💡 - - type: input - id: version - attributes: - label: Library Version - description: What version of the library are you currently using? - placeholder: "v1.0.0" - validations: - required: true + AfterTouch is a community-built toolkit for keeping Bose SoundTouch speakers + alive. For open-ended "would it be possible...?" brainstorming, + [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) is often + a better fit. Use this form when you have a concrete improvement in mind. - type: textarea id: problem attributes: - label: Problem Description - description: Is your feature request related to a problem? Please describe what you're trying to accomplish. - placeholder: "I'm always frustrated when... / I need to be able to... / Currently it's not possible to..." + label: What problem would this solve? + placeholder: "I can't ... / It's hard to ... / Currently there's no way to ..." validations: required: true - type: textarea - id: solution + id: idea attributes: - label: Proposed Solution - description: Describe the solution you'd like to see implemented. - placeholder: "I would like to see... / A new function that... / An option to..." + label: What would you like to see? + placeholder: "Describe the feature or improvement you have in mind." validations: required: true + - type: dropdown + id: area + attributes: + label: Which part of AfterTouch? + multiple: true + options: + - "soundtouch-service (local cloud)" + - "soundtouch-cli" + - "soundtouch-player (web UI)" + - "soundtouch-backup" + - "Go library (pkg/*)" + - "Documentation" + - "Not sure" + validations: + required: false + - type: textarea id: alternatives attributes: - label: Alternatives Considered - description: Describe any alternative solutions or features you've considered. - placeholder: "I considered... / Another approach could be... / Workaround I'm currently using..." - validations: - required: false - - - type: dropdown - id: component - attributes: - label: Component - description: Which component would this feature affect? - multiple: true - options: - - "Client Library (pkg/client)" - - "WebSocket Events" - - "Device Discovery" - - "CLI Tool" - - "Models/XML Parsing" - - "Documentation" - - "Examples" - - "New API Endpoint" - - "Performance Optimization" - - "Developer Experience" - validations: - required: true - - - type: dropdown - id: device-compatibility - attributes: - label: Device Compatibility - description: Which Bose SoundTouch devices should this feature support? - multiple: true - options: - - "All SoundTouch devices" - - "SoundTouch 10" - - "SoundTouch 20" - - "SoundTouch 30" - - "SoundTouch Portable" - - "SoundTouch Wave" - - "Other (specify in description)" - validations: - required: false - - - type: dropdown - id: priority - attributes: - label: Priority - description: How important is this feature to you? - options: - - "Low - Nice to have" - - "Medium - Would improve my workflow" - - "High - Important for my use case" - - "Critical - Blocking my project" - validations: - required: true - - - type: dropdown - id: api-type - attributes: - label: API Type (if applicable) - description: What type of API enhancement is this? - options: - - "Not applicable" - - "New Bose SoundTouch endpoint" - - "Enhancement to existing endpoint" - - "Client library improvement" - - "WebSocket event enhancement" - - "Discovery enhancement" - - "CLI command addition" - validations: - required: false - - - type: textarea - id: use-case - attributes: - label: Use Case / User Story - description: Describe your specific use case or user story - placeholder: | - As a [type of user], I want to [goal] so that [benefit]. - - Example: As a home automation developer, I want to create custom zones so that I can group speakers dynamically based on user preferences. - validations: - required: true - - - type: textarea - id: example-api - attributes: - label: Desired API Example - description: Show how you'd like the API to work (if applicable) - render: go - placeholder: | - // Example of how you envision using this feature - client := soundtouch.New("192.0.2.100", 8090) - - // Your desired API call - result, err := client.NewFeature(options) - if err != nil { - // handle error - } - - // Use the result - fmt.Println(result) - validations: - required: false - - - type: textarea - id: technical-details - attributes: - label: Technical Details - description: Any technical considerations, constraints, or implementation ideas? - placeholder: | - - Should this be backward compatible? - - Any performance considerations? - - Integration with existing features? - - External dependencies needed? + label: Alternatives or workarounds + description: Anything you've already tried or considered. Links and references are welcome. + placeholder: "See the API Cookbook (https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-COOKBOOK/) ..." validations: required: false - type: checkboxes - id: implementation + id: help attributes: - label: Implementation - description: Are you willing to help implement this feature? + label: Can you help? + description: Completely optional. Community contributions are very welcome. options: - - label: "I can help implement this feature" - - label: "I can provide testing/feedback" + - label: "I can help implement this" + - label: "I can help test it" - label: "I can help with documentation" - - label: "I need someone else to implement this" - - - type: textarea - id: research - attributes: - label: Research & References - description: Have you found any relevant resources, similar implementations, or Bose documentation? - placeholder: | - - Links to relevant documentation - - Similar features in other libraries - - Bose SoundTouch API references - - Related GitHub issues or discussions - validations: - required: false - type: checkboxes - id: checklist - attributes: - label: Checklist - description: Please confirm the following - options: - - label: "I have searched for existing issues and feature requests" - required: true - - label: "I have checked the [API Cookbook](docs/API-COOKBOOK.md) for existing functionality" - required: true - - label: "This feature is related to Bose SoundTouch functionality" - required: true - - label: "I have considered backward compatibility" - - - type: checkboxes - id: terms + id: coc attributes: label: Code of Conduct - description: By submitting this feature request, you agree to follow our Code of Conduct + description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md). options: - label: "I agree to follow this project's Code of Conduct" required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1fa2ce0..af753e4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,171 +1,45 @@ -## Description +## Summary -Brief description of the changes in this PR. +What does this PR do, and why? -## Type of Change +## Linked issue -Please check the type of change your PR introduces: + +Refs # -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] Documentation update -- [ ] Performance improvement -- [ ] Code refactoring (no functional changes) -- [ ] Test improvements -- [ ] Build/CI improvements +## Type of change -## Related Issues +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation +- [ ] Refactor / tests / tooling -- Fixes #[issue number] -- Relates to #[issue number] -- Part of #[issue number] +## How was it tested? -## Changes Made +- [ ] `make check` passes (fmt, vet, lint, tests) +- [ ] Tested against a real SoundTouch device (details below) -### API Changes -- [ ] Added new endpoints -- [ ] Modified existing endpoints -- [ ] Added new CLI commands -- [ ] Modified existing CLI commands -- [ ] Added new configuration options + -### Implementation Details -- Describe the main changes -- List any new dependencies -- Mention any architectural changes +## Checklist -## Testing - -### Automated Tests -- [ ] Unit tests added/updated -- [ ] Integration tests added/updated -- [ ] All existing tests pass -- [ ] Test coverage maintained or improved - -### Manual Testing -- [ ] Tested with real SoundTouch device(s) -- [ ] Tested CLI changes manually -- [ ] Tested in different network environments - -**Device(s) tested with:** -- Device model: [e.g. SoundTouch 10] -- Device IP: [e.g. 192.0.2.100] -- Test results: [brief description] - -### Test Commands -```bash -# Commands used to test this change -make test -go test ./pkg/client -v -run TestNewFeature -soundtouch-cli --host 192.0.2.100 new-command -``` - -## Documentation - -- [ ] Updated relevant documentation -- [ ] Added code comments for complex logic -- [ ] Updated CLI help text -- [ ] Added usage examples -- [ ] Updated API documentation - -**Documentation files updated:** -- [ ] README.md -- [ ] docs/API-Endpoints-Overview.md -- [ ] docs/CLI-REFERENCE.md -- [ ] Code documentation (godoc) - -## Backward Compatibility - -- [ ] This change is backward compatible -- [ ] This change includes breaking changes (requires major version bump) -- [ ] This change requires configuration migration - -**Breaking changes (if any):** -- Describe what breaks -- Provide migration instructions - -## Security Considerations - -- [ ] No security implications -- [ ] Security review required -- [ ] Added input validation -- [ ] Updated authentication/authorization - -## Performance Impact - -- [ ] No performance impact -- [ ] Performance improvement -- [ ] Potential performance regression (justify why) - -**Performance notes:** -- Measured impact: [benchmarks, timing, memory usage] -- Optimization opportunities: [if any] - -## Code Quality - -- [ ] Code follows project style guidelines -- [ ] No linting errors -- [ ] No security warnings -- [ ] Memory leaks checked (if applicable) - -### Pre-submission Checklist - -- [ ] `make check` passes (format, lint, vet) -- [ ] `make test` passes -- [ ] No TODO comments left in production code -- [ ] Error handling is comprehensive -- [ ] Logging is appropriate (not too verbose, not too quiet) - -## Deployment Notes - -Any special considerations for deployment: -- Configuration changes required -- Database migrations needed -- Service restart required -- Rollback procedures - -## Screenshots (if applicable) - -If this PR includes UI changes or CLI output changes, include screenshots or terminal output examples. - -```bash -# Before -$ soundtouch-cli old-command -Old output... - -# After -$ soundtouch-cli new-command -New improved output... -``` - -## Additional Notes - -Any additional information that reviewers should know: -- Design decisions and trade-offs -- Future work planned -- Alternative approaches considered -- References to external documentation - -## Review Requests - -**Areas that need special attention:** -- [ ] Error handling logic -- [ ] Performance critical sections -- [ ] Security implications -- [ ] API design choices -- [ ] Documentation clarity - -**Specific questions for reviewers:** -1. Question about design choice X? -2. Is error handling sufficient in section Y? -3. Should we consider alternative approach Z? +- [ ] My changes are focused, and I have read the diff myself +- [ ] No personal data (real LAN IPs, MAC addresses, device IDs, account IDs) in code, tests, or fixtures +- [ ] Docs or CLI help updated if behavior changed --- -**Reviewer Guidelines:** -- Check that all tests pass -- Verify documentation is updated -- Test manually if device access available -- Consider backward compatibility -- Evaluate error handling and edge cases \ No newline at end of file +### A note on AI-assisted contributions + +AI and agent-assisted code is welcome, we use it here too. What we cannot accept is +unreviewed "slop": large generated diffs the author has not read, run, or understood. +Keep PRs small and focused, make sure `make check` passes, and be ready to explain your +changes during review. + +By contributing, you agree that your work is licensed under the project's +[MIT License](https://github.com/gesellix/Bose-SoundTouch/blob/main/LICENSE) and that you +will follow the +[Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b154627..2a7de2e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,498 +1,185 @@ -# Contributing to Bose SoundTouch API Client +# Contributing to AfterTouch -Thank you for your interest in contributing to the Bose SoundTouch API Client! This project aims to provide a comprehensive, reliable, and well-tested Go library for controlling Bose SoundTouch devices. +Thank you for your interest in contributing to **AfterTouch**! -## Ways to Contribute +AfterTouch is a community-built toolkit that keeps Bose SoundTouch speakers +usable after Bose shut down the SoundTouch cloud. It is a Go codebase that ships +several tools plus a reusable library: -All contributions are welcome — large or small: +- **soundtouch-service** the local cloud replacement (emulates `streaming.bose.com` and the `bmx` services) +- **soundtouch-cli** command-line control of one or more speakers +- **soundtouch-player** the web UI for radio browsing and device control +- **soundtouch-backup** on-device backup and restore helper +- **pkg/** the underlying Go library (HTTP + WebSocket client, models, discovery, ...) -- **Code suggestions** — bug fixes, new features, refactoring, performance improvements. -- **Documentation updates** — README, guides, examples, troubleshooting notes, inline doc comments. -- **Bug fixes** — even just a clear reproducer in an issue is a real contribution. -- **Donations** — if the project kept a speaker (or several) of yours alive past the Bose cloud shutdown and you want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is open. No expectation; everything in this repo stays MIT regardless. +We are an open community: we both provide and ask for support. Contributions of +every size are welcome, and you do not need to be a Go developer to help. -By submitting a code or documentation contribution you agree to license it under MIT. The detailed guides below cover the mechanics. +## Ways to contribute -## Table of Contents +- **Bug reports** even a clear reproducer is a real contribution. An attached + diagnostic report (see [Reporting issues](#reporting-issues)) helps enormously. +- **Device compatibility reports** tell us how AfterTouch behaves with your speaker model. +- **Code** bug fixes, features, refactoring, tests, tooling. +- **Documentation** guides, examples, troubleshooting notes, inline doc comments. +- **Helping others** answering questions in [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions). +- **Donations** if AfterTouch kept a speaker (or several) of yours alive and you + want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is + open. There is no expectation, and everything here stays MIT regardless. -- [Code of Conduct](#code-of-conduct) -- [Getting Started](#getting-started) -- [How Can I Contribute?](#how-can-i-contribute) -- [Development Setup](#development-setup) -- [Pull Request Process](#pull-request-process) -- [Coding Guidelines](#coding-guidelines) -- [Testing Guidelines](#testing-guidelines) -- [Documentation Guidelines](#documentation-guidelines) -- [Reporting Issues](#reporting-issues) -- [Device Testing](#device-testing) -- [Community](#community) -- [Support the Project](#support-the-project) +By submitting a code or documentation contribution you agree to license it under +the project's [MIT License](LICENSE). ## Code of Conduct -This project adheres to our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. +This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, +you agree to uphold it. Please report unacceptable behavior to the maintainer. -## Getting Started +## Getting started ### Prerequisites -- **Go 1.25.6 or later**: [Download Go](https://golang.org/dl/) -- **Git**: For version control -- **Make**: For build automation (optional but recommended) -- **SoundTouch Device**: For testing (optional but valuable) +- **Go** (version per [`go.mod`](go.mod), currently the 1.26.x series) +- **Git** +- **Make** (recommended; drives builds and the quality gate) +- **Docker** (only needed for the HTTP-client integration tests) +- A **SoundTouch device** is optional but valuable for testing -### First Contribution - -1. **Fork the repository** on GitHub -2. **Clone your fork** locally: - ```bash - git clone https://github.com/YOUR-USERNAME/Bose-SoundTouch.git - cd Bose-SoundTouch - ``` -3. **Install dependencies**: - ```bash - go mod download - ``` -4. **Run tests** to ensure everything works: - ```bash - make test - # or - go test ./... - ``` -5. **Build the CLI** to test functionality: - ```bash - make build - ./soundtouch-cli --help - ``` - -## How Can I Contribute? - -### 🐛 Reporting Bugs - -Before creating a bug report, please: - -1. **Check existing issues** to avoid duplicates -2. **Test with the latest version** from the main branch -3. **Include device information** (model, firmware version if known) - -When filing a bug report, include: - -- **Clear title** describing the issue -- **Steps to reproduce** the behavior -- **Expected behavior** vs actual behavior -- **Environment details**: OS, Go version, device model -- **Log output** if applicable (use `--verbose` flag) - -### 💡 Suggesting Features - -Feature requests are welcome! Please: - -1. **Check if the feature already exists** in documentation -2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/content/docs/reference/API-ENDPOINTS.md)) -3. **Explain the use case** and how it benefits users - -### 🔧 Contributing Code - -Areas where contributions are especially welcome: - -#### High Priority -- **Bug fixes** for existing functionality -- **Device compatibility** improvements -- **Error handling** enhancements -- **Performance optimizations** - -#### Medium Priority -- **New endpoint implementations** (if officially documented) -- **CLI improvements** (better UX, additional commands) -- **Documentation improvements** -- **Example applications** - -#### Future Enhancements -- **Web interface** development -- **Home Assistant integration** -- **WASM/browser support** -- **Mobile app development** - -## Development Setup - -### Project Structure - -``` -Bose-SoundTouch/ -├── cmd/ # Command-line applications -│ ├── soundtouch-cli/ # Main CLI tool -│ └── examples/ # Example applications -├── pkg/ # Library packages -│ ├── client/ # HTTP client implementation -│ ├── discovery/ # Device discovery -│ ├── models/ # Data structures -│ └── config/ # Configuration management -├── docs/ # Documentation -├── examples/ # Usage examples -└── scripts/ # Build and utility scripts -``` - -### Development Commands +### Build and run ```bash -# Run tests -make test +# Clone your fork +git clone https://github.com/YOUR-USERNAME/Bose-SoundTouch.git +cd Bose-SoundTouch -# Run tests with coverage -make test-coverage - -# Build all binaries +# Build all binaries into ./build/ make build -# Run linting and formatting -make check +# Try the CLI +./build/soundtouch-cli --help -# Run golangci-lint specifically -golangci-lint run - -# Auto-fix linting issues where possible -golangci-lint run --fix - -# Install CLI locally -go install ./cmd/soundtouch-cli - -# Run integration tests (requires real device) -make test-integration HOST=192.0.2.100 +# Run the local service on port 8000 +make dev-service ``` -### Environment Setup +Other useful targets: `make build-cli`, `make build-service`, `make build-player`, +`make dev-discover` (find devices on the LAN). See the `Makefile` for the full list. -For development with real devices, create a `.env` file: +## Development workflow -```env -# Optional: Pre-configured device for testing -SOUNDTOUCH_HOST=192.0.2.100 -SOUNDTOUCH_PORT=8090 - -# Optional: Enable debug logging -SOUNDTOUCH_DEBUG=true -``` - -## Pull Request Process - -### Before Submitting - -1. **Create an issue** first for significant changes -2. **Fork and create a feature branch**: +1. For anything non-trivial, **open an issue first** so we can agree on the approach. +2. Create a feature branch from `main`. +3. Make small, focused changes with tests. +4. Run the quality gate before pushing: ```bash - git checkout -b feature/your-feature-name - ``` -3. **Write tests** for your changes -4. **Update documentation** if needed -5. **Run the full test suite**: - ```bash - make check - make test + make check # fmt + vet + tests (+ the Docker-based HTTP-client integration suite) + make lint # golangci-lint, must be clean ``` + If you do not have Docker handy, run `make test` and `make lint` and say so in + the PR; CI runs the full gate on every PR. +5. Open a pull request. The PR template walks you through what to include. -### Pull Request Guidelines +New to the codebase? **[`CLAUDE.md`](CLAUDE.md)** is the entry point for any +session (human or AI): it explains the layout, build/test commands, and the +load-bearing gotchas. Please skim it before larger changes. -1. **Clear title** describing the change -2. **Detailed description** explaining: - - What the change does - - Why it's needed - - How it was tested - - Any breaking changes -3. **Link to related issues** -4. **Update CHANGELOG.md** if applicable -5. **Ensure CI passes** +### A note on AI-assisted contributions -### Review Process +AI and agent-assisted code is welcome, we use it here too. What we cannot accept +is unreviewed "slop": large generated diffs the author has not read, run, or +understood. Keep PRs small and focused, make sure `make check` passes, and be +ready to explain your changes during review. -- At least one maintainer will review your PR -- Feedback will be constructive and specific -- Address feedback in additional commits -- Once approved, a maintainer will merge your PR +### Never commit personal or device data -## Coding Guidelines +This repository is public. Do not commit real LAN IPs, MAC addresses, device IDs, +Bose account IDs, tokens, firmware binaries, or Wi-Fi credentials, in code, tests, +fixtures, commit messages, or PR text. Use the RFC-5737 documentation ranges +(`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) and placeholder identifiers +in examples. See [`CLAUDE.md`](CLAUDE.md) for the full list. -### Go Style +## Coding and testing guidelines -Follow standard Go conventions: +- **Follow standard Go style:** `gofmt`, `go vet`, and `golangci-lint` all clean. + `golangci-lint run --fix` auto-fixes some issues. +- **Tests are expected** with every change. Prefer unit tests with `httptest` + mocks; use integration tests where a unit test is impractical. +- **Use real device data for fixtures where possible,** anonymized per the rule + above. Reproducer tests should graduate into permanent regression or + documentation tests rather than being deleted. +- **Wrap errors with context** (`fmt.Errorf("...: %w", err)`) and validate inputs + with helpful messages. +- **Keep it simple.** Favor readable, self-explanatory code over cleverness. +- **The SoundTouch Web API is XML on the wire;** internal service-to-service + messages are JSON. (One sharp edge: the `ETag` response header must keep its + exact capitalization, see `CLAUDE.md`.) -- **gofmt** for formatting -- **golangci-lint** for comprehensive code quality checks -- **go vet** for static analysis -- **Effective Go** principles -- **Standard library patterns** where applicable +## Reporting issues -### Code Organization +Open a [new issue](https://github.com/gesellix/Bose-SoundTouch/issues) and pick +one of the forms; they keep reports easy to triage: -```go -// Package-level documentation -package client +- **Bug report** something in AfterTouch is not working as it should +- **Feature request** an idea or improvement +- **Device compatibility report** how AfterTouch behaves with your speaker model -import ( - // Standard library first - "context" - "encoding/xml" - - // Third-party packages - "github.com/gorilla/websocket" - - // Local packages - "github.com/gesellix/bose-soundtouch/pkg/models" -) +For bugs, the most helpful thing you can attach is an **encrypted diagnostic +report**. In the AfterTouch admin UI, open the **Health tab** and click +**Download diagnostic report**. The file is encrypted to the maintainer's key, so +only the maintainer can open it. -// Public API should be well-documented -// GetDeviceInfo retrieves comprehensive device information including -// model, capabilities, network status, and current configuration. -func (c *Client) GetDeviceInfo() (*models.DeviceInfo, error) { - // Implementation -} -``` +To share it, the Health tab recommends **email**: send it to +. You can also attach it to a GitHub issue, but +GitHub blocks `.age` uploads, so rename the file to `.age.txt` (or zip it) first. -### Error Handling +To be transparent about what it holds: the structured summary (`diagnostic.json`) +and `settings.json` have credentials and OAuth secrets redacted, but the raw +datastore files (for example `Sources.xml` and `full.xml`) are included **as-is**. +For TuneIn, Radio Browser, and Local Internet Radio those carry only +AfterTouch-generated placeholders, but for **linked accounts such as Spotify or +Amazon they can contain the access tokens your speaker uses**. There is currently +no setting that redacts the datastore files. If that is a concern, unlink those +services before exporting, or email the report privately rather than attaching it +to a public issue. -- **Return errors** instead of panicking -- **Wrap errors** with context using `fmt.Errorf` -- **Create custom error types** for specific conditions -- **Validate inputs** and return helpful error messages +Before filing, the +[Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/) +often has the answer. For "how do I...?" questions, please use +[Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) rather than +the issue tracker. -```go -// Good error handling example -func (c *Client) SetVolume(level int) error { - if level < 0 || level > 100 { - return fmt.Errorf("volume level %d out of range [0-100]", level) - } - - if err := c.post("/volume", volumeXML); err != nil { - return fmt.Errorf("failed to set volume to %d: %w", level, err) - } - - return nil -} -``` +### Security issues -### API Design - -- **Consistent method naming**: `Get*`, `Set*`, `Send*`, etc. -- **Return pointers** for complex types, values for simple types -- **Accept contexts** for potentially long-running operations -- **Provide convenience methods** for common operations - -## Testing Guidelines - -### Test Structure - -```go -func TestClient_SetVolume(t *testing.T) { - tests := []struct { - name string - volume int - expectedError string - setupMock func(*httptest.Server) - }{ - { - name: "valid volume level", - volume: 50, - setupMock: func(server *httptest.Server) { - // Mock setup - }, - }, - { - name: "volume too high", - volume: 150, - expectedError: "volume level 150 out of range", - }, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - // Test implementation - }) - } -} -``` - -### Test Categories - -1. **Unit Tests**: Test individual functions with mocks -2. **Integration Tests**: Test with real devices (when available) -3. **Benchmark Tests**: Performance testing for critical paths - -### Mock Usage - -Use `httptest.Server` for HTTP client testing: - -```go -func setupMockServer() *httptest.Server { - return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - switch r.URL.Path { - case "/info": - w.Header().Set("Content-Type", "application/xml") - fmt.Fprint(w, mockDeviceInfoXML) - default: - w.WriteHeader(http.StatusNotFound) - } - })) -} -``` - -### Real Device Testing - -When possible, test with real SoundTouch devices: - -```bash -# Set device IP for integration tests -export SOUNDTOUCH_HOST=192.0.2.100 -go test -tags integration ./pkg/client/ -``` - -## Documentation Guidelines - -### Code Documentation - -- **Package documentation** for every package -- **Function documentation** for all public functions -- **Example documentation** for complex usage - -```go -// Package client provides a comprehensive HTTP client for the Bose SoundTouch Web API. -// -// The client supports all documented SoundTouch endpoints including device information, -// playback control, volume management, and real-time WebSocket events. -// -// Basic usage: -// -// client := client.NewClient(&client.Config{ -// Host: "192.0.2.100", -// Port: 8090, -// }) -// -// info, err := client.GetDeviceInfo() -// if err != nil { -// log.Fatal(err) -// } -// -// fmt.Printf("Device: %s\n", info.Name) -package client -``` - -### User Documentation - -- **README.md**: Overview and quick start -- **API documentation**: Comprehensive endpoint reference -- **Examples**: Real-world usage patterns -- **Troubleshooting**: Common issues and solutions - -### Documentation Updates - -When making changes: - -1. **Update relevant docs** in the same PR -2. **Include usage examples** for new features -3. **Update CLI help text** if applicable -4. **Test documentation** (ensure examples work) - -## Device Testing - -### Supported Devices - -The library has been tested with: - -- **SoundTouch 10** (firmware unknown) -- **SoundTouch 20** (firmware unknown) - -### Testing New Devices - -If you have access to other SoundTouch models: - -1. **Run discovery** to find devices: - ```bash - ./soundtouch-cli discover devices - ``` - -2. **Test basic functionality**: - ```bash - ./soundtouch-cli -h 192.0.2.100 info get - ./soundtouch-cli -h 192.0.2.100 now-playing get - ``` - -3. **Report compatibility** in your PR or issue -4. **Include device information** from the info endpoint - -### Testing Protocol - -For significant changes: - -1. **Test on multiple devices** if available -2. **Test error scenarios** (device offline, network issues) -3. **Test edge cases** (invalid inputs, boundary conditions) -4. **Document any device-specific behavior** - -## Reporting Issues - -### Security Issues - -**Do not open public issues for security vulnerabilities.** Instead: - -1. **Email the maintainers** with details -2. **Allow reasonable time** for response -3. **Coordinate disclosure** timing - -### Bug Reports - -Use the bug report template and include: - -- **Device model and firmware** (if known) -- **Complete error messages and logs** -- **Minimal reproduction case** -- **Environment information** - -### Feature Requests - -Use the feature request template and include: - -- **Clear description** of the desired functionality -- **Use case explanation** -- **API documentation reference** (if applicable) -- **Alternative solutions** you've considered +Please do not open a public issue for a security vulnerability. Report it +privately to the maintainer (GitHub's private vulnerability reporting on the +repository's Security tab is the preferred channel) and allow reasonable time for +a fix before any public disclosure. ## Community -### Communication Channels +- **Discussions:** questions, ideas, and general support +- **Issues:** bugs, feature requests, compatibility reports +- **Pull requests:** code and documentation -- **GitHub Issues**: Bug reports, feature requests -- **GitHub Discussions**: Questions, ideas, general discussion -- **Pull Requests**: Code contributions and reviews +Please be patient and respectful in all interactions. Significant contributions +are credited in release notes. -### Getting Help - -1. **Check existing documentation** first -2. **Search closed issues** for similar problems -3. **Create a new issue** with detailed information -4. **Be patient and respectful** in all interactions - -### Recognition - -Contributors will be: - -- **Listed in CONTRIBUTORS.md** -- **Mentioned in release notes** for significant contributions -- **Credited in documentation** where appropriate - -## Support the Project - -If you want to support the maintenance effort beyond code: +## Support the project [![GitHub Sponsors](https://img.shields.io/github/sponsors/gesellix?label=Sponsor%20on%20GitHub&logo=GitHub&color=ea4aaa)](https://github.com/sponsors/gesellix) -Sponsorship is entirely optional. Code, docs, and bug reports remain the most useful contributions for the project itself. +Sponsorship is entirely optional. Code, docs, bug reports, and helping others +remain the most useful contributions. -## Additional Resources +## Resources -- [Go Documentation](https://golang.org/doc/) -- [Effective Go](https://golang.org/doc/effective_go.html) -- [Bose SoundTouch API Documentation](docs/content/docs/reference/API-ENDPOINTS.md) -- [Project Architecture](docs/content/docs/appendix/PROJECT-PATTERNS.md) -- [Development Status](docs/archive/STATUS.md) +- [AfterTouch documentation](https://gesellix.github.io/Bose-SoundTouch/) +- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/) +- [API Cookbook](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-COOKBOOK/) +- [API Endpoints](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-ENDPOINTS/) +- [Go Documentation](https://golang.org/doc/) and [Effective Go](https://golang.org/doc/effective_go.html) --- -**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community. +**Thank you for contributing!** Every contribution helps keep the SoundTouch +community's speakers playing.