Contributing - Aceplay

Contributions to Aceplay are welcome! This guide covers the contribution workflow, code style, and pull request process.

Getting Started

Fork the repository

Create your own fork of the repository on GitHub:

# Click "Fork" on https://github.com/crstian19/aceplay

Clone your fork

git clone https://github.com/YOUR_USERNAME/aceplay.git
cd aceplay

Create a feature branch

git checkout -b feature/amazing-feature

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation updates
refactor/ - Code refactoring

Install dependencies

make deps

Development Workflow

1. Make Your Changes

Write clean, well-documented code following the code style guidelines.

2. Add Tests

All new features and bug fixes should include tests:

# Run tests as you develop
make test

# Check coverage
make test-coverage

See Testing for details.

3. Run Quality Checks

Before committing, run all checks:

make check

This runs:

make fmt - Format code
make vet - Static analysis
make lint - Linting
make test - Full test suite

Always run make check before committing. Pull requests that don’t pass these checks will not be merged.

4. Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add support for custom player arguments"

Good commit messages:

“Add support for custom player arguments”
“Fix race condition in stream initialization”
“Update configuration documentation”

Bad commit messages:

“Fixed stuff”
“WIP”
“Updates”

5. Push to Your Fork

git push origin feature/amazing-feature

6. Open a Pull Request

On GitHub:

Navigate to your fork
Click “Pull Request”
Select your feature branch
Fill out the PR template with:
- Description of changes
- Related issue numbers (if any)
- Testing performed
- Screenshots (for UI changes)

Code Style Guidelines

General Principles

From AGENTS.md:

Write clean, readable Go code
Follow standard Go conventions
Keep functions focused and small (single responsibility)
Use meaningful variable and function names
Add comments for exported functions and types

Naming Conventions

// Variables: camelCase
configPath := "/path/to/config"
isFirstRun := true

// Constants: PascalCase or camelCase for unexported
const DefaultPlayer = "mpv"
const maxRetries = 3

// Functions: PascalCase for exported, camelCase for unexported
func LoadConfig(path string) (*Config, error) { }
func isValidURL(url string) bool { }

// Types/Structs: PascalCase
type Config struct { }
type EngineConfig struct { }

// Interfaces: PascalCase with "er" suffix
type Reader interface { }
type ConfigLoader interface { }

Import Organization

Organize imports in groups (standard library first, then external):

import (
    "context"
    "fmt"
    "os"
    "time"

    "charm.land/lipgloss/v2"
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
    "github.com/stretchr/testify/assert"
)

Run make fmt to organize automatically.

Error Handling

Always handle errors explicitly:

// Good - wrap errors with context
if err != nil {
    return fmt.Errorf("failed to load config: %w", err)
}

// Good - early return on error
cfg, err := Load(configPath)
if err != nil {
    return fmt.Errorf("error loading configuration: %w", err)
}

// Bad - ignoring errors
_ = LoadConfig(path)

// Bad - no context
if err != nil {
    return err
}

Struct Tags

Use struct tags for configuration and serialization:

type Config struct {
    Player  string        `mapstructure:"player"`
    Engine  EngineConfig  `mapstructure:"engine"`
    Timeout time.Duration `mapstructure:"timeout"`
    HLS     bool          `mapstructure:"hls"`
}

Logging

Use the Charm log package consistently:

import "github.com/charmbracelet/log"

log.Info("starting application")
log.Debugf("config loaded from %s", configPath)
log.Errorf("failed to connect: %v", err)

CLI Commands

Use Cobra with helpful descriptions:

var playCmd = &cobra.Command{
    Use:   "play [acestream-url]",
    Short: "Play an Ace Stream URL",
    Long:  `Play Ace Stream content using your configured video player.`,
    Args:  cobra.ExactArgs(1),
    RunE:  runPlay,
}

Testing Requirements

Test Coverage

All new code should include tests:

New features: Add tests covering main functionality and edge cases
Bug fixes: Add regression tests to prevent recurrence
Refactoring: Ensure existing tests still pass

Target coverage:

Critical paths: 80%+
Utilities: 70%+
UI components: Best effort

Test Structure

Use table-driven tests:

func TestParseURL(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        wantID  string
        wantErr bool
    }{
        {"valid URL", "acestream://abc123", "abc123", false},
        {"invalid protocol", "http://example.com", "", true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            id, err := ParseURL(tt.input)
            if tt.wantErr {
                assert.Error(t, err)
            } else {
                assert.NoError(t, err)
                assert.Equal(t, tt.wantID, id)
            }
        })
    }
}

See Testing for detailed guidelines.

Documentation

Update documentation when:

Adding new features
Changing configuration options
Modifying CLI commands
Changing behavior

Documentation locations:

README.md - Project overview and quick start
AGENTS.md - Development guidelines
CHANGELOG.md - Version history
Code comments - Exported functions and types

Pull Request Guidelines

PR Checklist

Before submitting:

Code follows style guidelines
make check passes without errors
Tests added for new features/fixes
Documentation updated
Commit messages are clear and descriptive
PR description explains changes and motivation

PR Review Process

Automated checks: CI runs tests and linting
Code review: Maintainers review your changes
Feedback: Address review comments
Approval: PR is approved and merged

Responding to Feedback

When reviewers request changes:

Make the requested changes
Run make check again
Commit and push updates
Respond to review comments

# After making changes
git add .
git commit -m "Address review feedback: improve error handling"
git push origin feature/amazing-feature

Common Contribution Tasks

Adding a New Command

Create command file

Add command in appropriate package

Add tests

Create *_test.go file with test cases

Update documentation

Document in README.md and relevant docs

Adding a Configuration Option

Update Config struct

Add field to Config struct in internal/config/config.go

Set default value

Add default in NewConfig() function

Document in README

Add to configuration section with example

Add tests

Test loading and validation

Fixing a Bug

Write failing test

Create test that reproduces the bug

Fix the bug

Implement the fix

Verify test passes

Ensure the new test now passes

Run all tests

Make sure no regressions: make test

Dependencies

Adding Dependencies

When adding new dependencies:

# Add dependency
go get github.com/example/package@latest

# Clean up
make tidy

# Verify
go mod verify

Guidelines:

Keep dependencies minimal
Prefer well-maintained packages
Check license compatibility (MIT preferred)
Document why the dependency is needed

Updating Dependencies

# Update specific package
go get -u github.com/spf13/cobra@latest

# Update all dependencies
go get -u ./...

# Clean up
make tidy

Getting Help

If you need help:

Check existing issues: Search GitHub issues for similar problems
Read documentation: Review README.md and AGENTS.md
Ask questions: Open a GitHub issue with the “question” label
Join discussions: Participate in GitHub Discussions

Code of Conduct

Be respectful and constructive:

Use welcoming and inclusive language
Respect differing viewpoints and experiences
Accept constructive criticism gracefully
Focus on what is best for the community

Recognition

Contributors are recognized in:

GitHub contributors page
CHANGELOG.md for significant contributions
Project README for major features

Thank you for contributing to Aceplay!

Resources

Architecture

Understand the project structure

Building

Learn how to build from source

Testing

Testing guidelines and commands

Go Documentation

Official Go documentation

Get Started

Usage

Configuration

Advanced

Development

​Getting Started

​Development Workflow

​1. Make Your Changes

​2. Add Tests

​3. Run Quality Checks

​4. Commit Your Changes

​5. Push to Your Fork

​6. Open a Pull Request

​Code Style Guidelines

​General Principles

​Naming Conventions

​Import Organization

​Error Handling

​Struct Tags

​Logging

​CLI Commands

​Testing Requirements

​Test Coverage

​Test Structure

​Documentation

​Pull Request Guidelines

​PR Checklist

​PR Review Process

​Responding to Feedback

​Common Contribution Tasks

​Adding a New Command

​Adding a Configuration Option

​Fixing a Bug

​Dependencies

​Adding Dependencies

​Updating Dependencies

​Getting Help

​Code of Conduct

​Recognition

​Resources

Architecture

Building

Testing

Go Documentation

Build docs developers (and LLMs) love

Getting Started

Development Workflow

1. Make Your Changes

2. Add Tests

3. Run Quality Checks

4. Commit Your Changes

5. Push to Your Fork

6. Open a Pull Request

Code Style Guidelines

General Principles

Naming Conventions

Import Organization

Error Handling

Struct Tags

Logging

CLI Commands

Testing Requirements

Test Coverage

Test Structure

Documentation

Pull Request Guidelines

PR Checklist

PR Review Process

Responding to Feedback

Common Contribution Tasks

Adding a New Command

Adding a Configuration Option

Fixing a Bug

Dependencies

Adding Dependencies

Updating Dependencies

Getting Help

Code of Conduct

Recognition

Resources