Skip to content
Overview
Development
Contributing

Contributing

Thank you for your interest in contributing to SamWM! This guide explains how to contribute effectively.

Getting Started

Prerequisites

  • Go 1.22 or later
  • Git
  • Linux with Wayland support (for testing)

Setup Development Environment 

# Fork and clone
git clone https://github.com/YOUR_USERNAME/samwm.git
cd samwm

# Add upstream remote
git remote add upstream https://github.com/samouly/samwm.git

# Install dependencies
go mod download

How to Contribute

Reporting Bugs

  1. Check existing issues to avoid duplicates
  2. Create a new issue with:
    • Clear title and description
    • Steps to reproduce
    • Expected vs actual behavior
    • System information (OS, Go version)
    • Relevant logs or screenshots

Suggesting Features

  1. Check existing feature requests
  2. Create a new issue with:
    • Clear description of the feature
    • Use cases and motivation
    • Proposed implementation (if applicable)
    • Potential impact on existing features

Submitting Code

  1. Fork the repository
  2. Create a feature branch: 
    git checkout -b feature/my-feature
  3. Make your changes
  4. Add tests for new functionality
  5. Update documentation if needed
  6. Commit with clear messages: 
    git commit -m "feat: add my feature"
  7. Push to your fork: 
    git push origin feature/my-feature
  8. Create a pull request

Development Guidelines

Code Style

  • Follow Effective Go
  • Use gofmt and goimports
  • Write clear, self-documenting code
  • Add comments for complex logic

Commit Messages

Use conventional commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat(layout): add grid layout algorithm
fix(input): resolve keybinding conflict with shift modifier
docs(config): update keybinding documentation

Testing

  • Write tests for all new functionality
  • Maintain or improve test coverage
  • Use table-driven tests where appropriate
  • Test edge cases and error conditions
# Run all tests
make test

# Run with coverage
go test -coverprofile=coverage.out ./...

# Run specific tests
go test ./internal/config/...

Documentation

  • Update README.md for user-facing changes
  • Update docs/ for technical changes
  • Add doc comments for new exported functions
  • Include examples for new features

Pull Request Process

Before Submitting

  1. Test your changes:

    make test
make lint
make fmt

  2. Update documentation if needed

  3. Rebase on latest main:

    git fetch upstream
git rebase upstream/main

PR Description

Include in your PR description:

  • What changes were made
  • Why the changes were made
  • How to test the changes
  • Related issues (if any)

Review Process

  1. Maintainers will review your PR
  2. Address any feedback
  3. PR will be merged once approved

Code Review Guidelines

For Authors

  • Keep PRs focused and small
  • Write clear commit messages
  • Respond to feedback promptly
  • Be open to suggestions

For Reviewers

  • Be constructive and respectful
  • Focus on code quality and correctness
  • Test the changes locally if possible
  • Approve when ready

Community Guidelines

Be Respectful

  • Treat everyone with respect
  • Be constructive in feedback
  • Welcome newcomers
  • Be patient with questions

Be Constructive

  • Focus on the code, not the person
  • Provide actionable feedback
  • Suggest improvements, not just problems
  • Acknowledge good work

Development Workflow

Feature Development

  1. Plan the feature:

    • Understand requirements
    • Design the solution
    • Identify affected areas

  2. Implement the feature:

    • Write code
    • Add tests
    • Update documentation

  3. Test the feature:

    • Run all tests
    • Test manually if needed
    • Check edge cases

  4. Submit the feature:

    • Create PR
    • Address feedback
    • Merge when approved

Bug Fixing

  1. Reproduce the bug:

    • Understand the issue
    • Create a test case
    • Verify the fix

  2. Fix the bug:

    • Implement the fix
    • Add regression tests
    • Update documentation

  3. Verify the fix:

    • Run all tests
    • Test the specific scenario
    • Check for side effects

Release Process

Versioning

SamWM follows Semantic Versioning:

  • Major: Breaking changes
  • Minor: New features (backward compatible)
  • Patch: Bug fixes (backward compatible)

Changelog

Update CHANGELOG.md with:

  • New features
  • Bug fixes
  • Breaking changes
  • Deprecations

Getting Help

Resources

Questions

  • Check documentation first
  • Search existing issues
  • Ask in discussions
  • Be specific and provide context

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Recognition

Contributors will be recognized in:

  • CONTRIBUTORS.md
  • Release notes
  • Project documentation

Thank you for contributing to SamWM!