Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (127 loc) · 4.61 KB

CONTRIBUTING.md

File metadata and controls

180 lines (127 loc) · 4.61 KB
Raw

Contributing to GitWizard

First off, thank you for considering contributing to GitWizard! 🎉

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps which reproduce the problem
  • Provide specific examples to demonstrate the steps
  • Describe the behavior you observed after following the steps
  • Explain which behavior you expected to see instead and why
  • Include screenshots if relevant
  • Include your environment details (OS, Go version, Git version)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

  • Use a clear and descriptive title
  • Provide a step-by-step description of the suggested enhancement
  • Provide specific examples to demonstrate the steps
  • Describe the current behavior and explain the behavior you expected to see instead
  • Explain why this enhancement would be useful

Pull Requests

  • Fill in the required template
  • Follow the Go coding style
  • Include tests when adding features
  • Update documentation when needed
  • End all files with a newline

Development Setup

  1. Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/gitwiz.git
cd gitwiz
  1. Install dependencies
go mod download
  1. Create a branch
git checkout -b feature/your-feature-name
  1. Make your changes and test
go test ./...
go build -o gitwiz
./gitwiz --help
  1. Commit your changes
git commit -m "feat: add amazing feature"

Commit Message Guidelines

We follow Conventional Commits:

  • feat: - A new feature
  • fix: - A bug fix
  • docs: - Documentation only changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

Examples:

feat: add clipboard integration for issue references
fix: handle empty co-author list gracefully
docs: update keyboard navigation guide

Coding Guidelines

Security Requirements (Critical!)

  1. Never use go-git library - Always use os/exec for git operations

  2. Always use exec.Command() with separate arguments:

    // ✅ CORRECT
exec.Command("git", "commit", "-m", message)

// ❌ WRONG
exec.Command("sh", "-c", "git commit -m '"+message+"'")

  3. Validate all user input - Email validation, control character stripping, etc.

  4. Add timeouts to all external commands (2 seconds recommended)

  5. No panic() - Always handle errors gracefully

Code Style

  • Run go fmt before committing
  • Run go vet to catch common mistakes
  • Use meaningful variable names
  • Add comments explaining "why", not "what"
  • Keep functions small and focused
  • Write tests for new features

Testing

  • Write unit tests for new functionality
  • Ensure all tests pass: go test ./...
  • Test edge cases (empty input, invalid data, etc.)
  • Include examples in test names: TestExtractIssueReferences_WithJIRAFormat

Documentation

  • Update README.md if adding features
  • Update USAGE.md with examples
  • Update KEYBOARD_GUIDE.md for UI changes
  • Add inline comments for complex logic
  • Document security considerations

Project Structure

gitwiz/
├── main.go              # Entry point, CLI flags
├── internal/
│   ├── git/             # Git operations (MUST use exec.Command)
│   ├── logic/           # Business logic, message building
│   └── tui/             # Terminal UI (Charm Huh)
├── scripts/             # Utility scripts
└── docs/                # Documentation

Package Guidelines

  • internal/git - Only git operations, must be secure
  • internal/logic - Pure functions, no I/O
  • internal/tui - UI only, delegate logic to other packages

Review Process

  1. All submissions require review
  2. CI must pass (tests, linting, build)
  3. At least one maintainer approval required
  4. Address review comments promptly
  5. Keep PR focused on a single feature/fix

Questions?

Feel free to:

License

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

Thank you for contributing! 🙏