Bose-SoundTouch/CONTRIBUTING.md

Contributing to Bose SoundTouch API Client

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.

Ways to Contribute

All contributions are welcome — large or small:

• 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 is open. No expectation; everything in this repo stays MIT regardless.

By submitting a code or documentation contribution you agree to license it under MIT. The detailed guides below cover the mechanics.

Table of Contents

• Code of Conduct
• Getting Started
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Guidelines
• Testing Guidelines
• Documentation Guidelines
• Reporting Issues
• Device Testing
• Community
• Support the Project

Code of Conduct

This project adheres to our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

• Go 1.25.6 or later: Download Go
• Git: For version control
• Make: For build automation (optional but recommended)
• SoundTouch Device: For testing (optional but valuable)

First Contribution

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/Bose-SoundTouch.git
   cd Bose-SoundTouch
   

3. Install dependencies:

   go mod download
   

4. Run tests to ensure everything works:

   make test
   # or
   go test ./...
   

5. Build the CLI to test functionality:

   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)
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

# Run tests
make test

# Run tests with coverage
make test-coverage

# Build all binaries
make build

# Run linting and formatting
make check

# 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

Environment Setup

For development with real devices, create a .env file:

# 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:

   git checkout -b feature/your-feature-name
   

3. Write tests for your changes
4. Update documentation if needed
5. Run the full test suite:

   make check
   make test
   

Pull Request Guidelines

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

Review Process

• 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

Coding Guidelines

Go Style

Follow standard Go conventions:

• gofmt for formatting
• golangci-lint for comprehensive code quality checks
• go vet for static analysis
• Effective Go principles
• Standard library patterns where applicable

Code Organization

// Package-level documentation
package client

import (
    // Standard library first
    "context"
    "encoding/xml"
    
    // Third-party packages
    "github.com/gorilla/websocket"
    
    // Local packages
    "github.com/gesellix/bose-soundtouch/pkg/models"
)

// 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
}

Error Handling

• 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

// 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
}

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

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:

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:

# 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

// 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:

   ./soundtouch-cli discover devices
   

2. Test basic functionality:

   ./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

Community

Communication Channels

• GitHub Issues: Bug reports, feature requests
• GitHub Discussions: Questions, ideas, general discussion
• Pull Requests: Code contributions and reviews

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:

Sponsorship is entirely optional. Code, docs, and bug reports remain the most useful contributions for the project itself.

Additional Resources

• Go Documentation
• Effective Go
• Bose SoundTouch API Documentation
• Project Architecture
• Development Status

---

Thank you for contributing! Every contribution helps make this library better for the entire SoundTouch community.