Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
263 lines (193 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

263 lines (193 loc) · 5.26 KB

Contributing to go-bindiff-struct

Thank you for your interest in contributing to go-bindiff-struct! This document provides guidelines and instructions for contributing.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/go-bindiff-struct.git
cd go-bindiff-struct
  3. Add the upstream repository: 
    git remote add upstream https://github.com/BaseMax/go-bindiff-struct.git

Development Setup

Prerequisites

  • Go 1.21 or later
  • Git
  • Make (optional, but recommended)

Building

# Using make
make build

# Or directly with go
go build -o bin/go-bindiff-struct ./cmd/go-bindiff-struct

Running Tests

# Using make
make test

# Or directly with go
go test ./...

Code Formatting

# Format code
make fmt

# Or
go fmt ./...

Linting

# Run go vet
make vet

# Or
go vet ./...

Making Changes

Branching Strategy

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Commit with clear messages:

    git commit -m "Add feature: description of what you added"

Commit Message Guidelines

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests after the first line

Example:

Add support for WASM binary format

- Implement WASM parser
- Add WASM to default registry
- Update documentation
- Add tests for WASM parsing

Fixes #123

Code Style

  • Follow standard Go conventions
  • Use gofmt to format your code
  • Write clear, self-documenting code
  • Add comments for exported functions and types
  • Keep functions focused and concise

Testing

Writing Tests

  • Add tests for all new functionality
  • Aim for high test coverage
  • Use table-driven tests where appropriate
  • Test both success and failure cases

Example:

func TestFeature(t *testing.T) {
    tests := []struct {
        name     string
        input    string
        expected string
    }{
        {"case1", "input1", "output1"},
        {"case2", "input2", "output2"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := Feature(tt.input)
            if result != tt.expected {
                t.Errorf("got %s, want %s", result, tt.expected)
            }
        })
    }
}

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific package tests
go test ./parser -v

Adding New Features

Adding a New Binary Format Parser

  1. Create a new file in parser/ (e.g., wasm.go)
  2. Implement the Parser interface: 
    type WASMParser struct{}

func (p *WASMParser) CanParse(r io.ReaderAt) bool { ... }
func (p *WASMParser) Parse(r io.ReaderAt, size int64) (*model.Binary, error) { ... }
func (p *WASMParser) Format() model.BinaryFormat { ... }
  3. Register in DefaultRegistry() in parser.go
  4. Add tests in parser_test.go
  5. Update documentation

Adding a New Diff Algorithm

  1. Add the algorithm to diff/engine.go
  2. Update the Diff() method to call your algorithm
  3. Create appropriate Change entries
  4. Add tests
  5. Update documentation

Adding a New Output Format

  1. Create a renderer in render/renderer.go
  2. Implement the Renderer interface
  3. Add to CLI format handling in cmd/go-bindiff-struct/main.go
  4. Add to API in api/client.go
  5. Add tests
  6. Update documentation

Documentation

  • Update README.md for user-facing changes
  • Update API.md for library API changes
  • Update ARCHITECTURE.md for architectural changes
  • Add examples for new features
  • Use clear, concise language
  • Include code examples

Pull Request Process

  1. Update documentation
  2. Add tests for new functionality
  3. Ensure all tests pass
  4. Update CHANGELOG.md (if present)
  5. Push to your fork
  6. Create a pull request

Pull Request Guidelines

  • Provide a clear description of the changes
  • Reference related issues
  • Include screenshots for UI changes (if applicable)
  • Keep PRs focused on a single concern
  • Respond to review comments promptly

PR Template

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How has this been tested?

## Checklist
- [ ] Code follows project style guidelines
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] All tests pass

Code Review

All submissions require review. We use GitHub pull requests for this purpose.

Reviewers will check for:

  • Code quality and style
  • Test coverage
  • Documentation
  • Performance implications
  • Security considerations

Security

If you discover a security vulnerability, please email the maintainer directly rather than opening a public issue.

License

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

Questions?

Feel free to open an issue for questions or discussions about contributing.

Recognition

Contributors will be acknowledged in the project README and release notes.

Thank you for contributing to go-bindiff-struct!