github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-24 14:47:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add comprehensive contributor guide and clean up documentation structure

Browse Source 
- Add CONTRIBUTING.md with detailed contributor guidelines
- Create GitHub issue templates (bug reports, feature requests, device compatibility)
- Add pull request template with comprehensive checklist
- Create FEATURE_HISTORY.md documenting development evolution
- Streamline README.md to focus on overview and usage
- Improve documentation organization and clarity

The project now has proper contribution guidelines following GitHub best practices,
making it easier for new contributors to get started and maintain consistent
quality standards.
This commit is contained in:
Tobias Gesellchen
2026-01-11 17:04:31 +01:00
parent e14df5d2ad
commit 89cb1b3927
7 changed files with 1422 additions and 954 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+77
View File
@@ -0,0 +1,77 @@
---
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.21.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.168.1.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
<!-- If the issue is device-specific, include output from: -->
<!-- soundtouch-cli --host YOUR_DEVICE_IP info get -->
```
**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
.github/ISSUE_TEMPLATE/device_compatibility.md
+113
View File
@@ -0,0 +1,113 @@
---
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
<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP info get -->
<!-- This helps us understand device capabilities and variants -->
```
**Device Capabilities Output**
```xml
<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP capabilities -->
<!-- This shows what features the device reports as available -->
```
**Bass Capabilities (if supported)**
```xml
<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP bass capabilities -->
<!-- Only if the device supports bass control -->
```
**Available Sources**
```xml
<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP source list -->
<!-- Shows what audio sources this device supports -->
```
**Testing Commands Used**
```bash
# List the specific commands you used for testing
soundtouch-cli --host 192.168.1.100 info get
soundtouch-cli --host 192.168.1.100 play start
# ... etc
```
**Environment**
- **OS**: [e.g. macOS 14.0, Windows 11, Ubuntu 22.04]
- **Go version**: [e.g. 1.21.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
.github/ISSUE_TEMPLATE/feature_request.md
+77
View File
@@ -0,0 +1,77 @@
---
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.168.1.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
.github/pull_request_template.md
+171
View File
@@ -0,0 +1,171 @@
## Description
Brief description of the changes in this PR.
## Type of Change
Please check the type of change your PR introduces:
- [ ] 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
## Related Issues
- Fixes #[issue number]
- Relates to #[issue number]
- Part of #[issue number]
## Changes Made
### 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
## 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.168.1.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.168.1.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?
---
**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