Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
189 lines (133 loc) · 4.39 KB

CONTRIBUTING.md

File metadata and controls

189 lines (133 loc) · 4.39 KB

Contributing to Tusk

Thank you for your interest in contributing to Tusk! This document provides guidelines and information for contributors.

Code of Conduct

Please be respectful and constructive in all interactions. We welcome contributors of all backgrounds and experience levels.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/tusk.git
cd tusk
  3. Add the upstream remote: 
    git remote add upstream https://github.com/hwkd/tusk.git
  4. Create a branch for your work: 
    git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Go 1.23 or later
  • golangci-lint (for linting)

Building

go build -o tusk ./cmd/tusk

Running Tests

go test ./...

With coverage:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Linting

golangci-lint run

Submitting Changes

Pull Request Process

  1. Ensure all tests pass
  2. Run the linter and fix any issues
  3. Update documentation if needed
  4. Write a clear commit message
  5. Push to your fork and create a pull request

Commit Messages

We follow the Conventional Commits specification.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (formatting, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files

Scope (optional)

The scope should be the name of the package or area affected:

  • auth - Authentication related changes
  • config - Configuration handling
  • googleapi - Google Tasks API client
  • ui - User interface/formatting
  • cmd - CLI commands
  • deps - Dependency updates

Subject Guidelines

  • Use the imperative, present tense: "add" not "added" nor "adds"
  • Don't capitalize the first letter
  • No period (.) at the end
  • Limit to 50 characters

Examples

feat(cmd): add prefix matching for task operations

fix(auth): handle token refresh errors gracefully

docs: update README with shell completion instructions

refactor(googleapi): simplify task list pagination

test(ui): add formatting tests for task output

chore(deps): update cobra to v1.8.1

Breaking Changes

Indicate breaking changes with ! after the type/scope or with a BREAKING CHANGE: footer:

feat(cmd)!: change default output format to JSON

BREAKING CHANGE: The default output format is now JSON instead of plain text.

Pull Request Guidelines

  • Keep changes focused and atomic
  • Include tests for new functionality
  • Update README.md if adding new features
  • Reference any related issues

Project Structure

tusk/
├── cmd/tusk/          # CLI commands
│   ├── main.go        # Entry point
│   ├── root.go        # Root command
│   ├── auth.go        # Authentication commands
│   ├── lists.go       # Task list commands
│   ├── tasks.go       # Task commands
│   └── aliases.go     # Command aliases
├── internal/          # Internal packages
│   ├── auth/          # OAuth2 authentication
│   ├── config/        # Configuration management
│   ├── googleapi/     # Google Tasks API client
│   └── ui/            # Output formatting
├── docs/              # Documentation
└── .github/           # GitHub workflows

Reporting Issues

When reporting issues, please include:

  1. Your operating system and version
  2. Go version (go version)
  3. Steps to reproduce the issue
  4. Expected vs actual behavior
  5. Any error messages or logs

Feature Requests

Feature requests are welcome! Please:

  1. Check existing issues to avoid duplicates
  2. Describe the use case clearly
  3. Explain why the feature would be valuable

Questions?

Feel free to open an issue for questions or discussions.

License

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