CONTRIBUTING.md

Contributing to go-binspect

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

Code of Conduct

Be respectful and inclusive. We welcome contributions from everyone.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

• A clear description of the problem
• Steps to reproduce
• Expected behavior
• Actual behavior
• Sample file (if applicable)
• Your operating system and Go version

Suggesting Features

We welcome feature suggestions! Please open an issue with:

• A clear description of the feature
• Use cases and benefits
• Any implementation ideas you have

Contributing Code

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes

   • Follow the existing code style
   • Add tests for new functionality
   • Update documentation as needed

4. Run tests

   make test

5. Commit your changes

   git commit -m "Add: Brief description of your changes"

6. Push to your fork

   git push origin feature/your-feature-name

7. Open a Pull Request

Development Setup

Prerequisites

• Go 1.21 or later (tested with Go 1.24)
• Git

Getting Started

# Clone the repository
git clone https://github.com/BaseMax/go-binspect.git
cd go-binspect

# Install dependencies
make deps

# Build the project
make build

# Run tests
make test

Project Structure

go-binspect/
├── cmd/binspect/          # Main application
├── internal/
│   ├── parser/            # File format parsers
│   ├── reader/            # Binary reading utilities
│   └── ui/                # TUI components
├── examples/              # Example outputs
└── README.md

Adding a New Parser

To add support for a new file format:

1. Create a new parser file in internal/parser/:

   // internal/parser/myformat.go
   package parser
   
   type MyFormatParser struct{}
   
   func NewMyFormatParser() *MyFormatParser {
       return &MyFormatParser{}
   }
   
   func (p *MyFormatParser) GetName() string {
       return "MyFormat"
   }
   
   func (p *MyFormatParser) Detect(data []byte) bool {
       // Implement format detection logic
       return false
   }
   
   func (p *MyFormatParser) Parse(reader interface{}) (*FileInfo, error) {
       // Implement parsing logic
       return nil, nil
   }

2. Add tests in internal/parser/myformat_test.go

3. Register the parser in cmd/binspect/main.go:

   registry.Register(parser.NewMyFormatParser())

4. Update documentation in README.md

Code Style

• Follow standard Go formatting (gofmt)
• Use meaningful variable names
• Add comments for exported functions
• Keep functions focused and small
• Write tests for new functionality

Testing

• All new code should have tests
• Tests should be in *_test.go files
• Run tests with make test
• Aim for good test coverage

Test Examples

func TestMyParser_Detect(t *testing.T) {
    parser := NewMyParser()
    
    validData := []byte{...}
    if !parser.Detect(validData) {
        t.Error("Expected parser to detect valid file")
    }
    
    invalidData := []byte{...}
    if parser.Detect(invalidData) {
        t.Error("Expected parser to reject invalid file")
    }
}

Documentation

• Update README.md for user-facing changes
• Add examples to examples/ directory
• Document new parsers and features
• Keep comments up to date

Pull Request Guidelines

• Keep PRs focused on a single feature or fix
• Write clear commit messages
• Update tests and documentation
• Ensure all tests pass
• Respond to review feedback

Good Commit Messages

Add: Support for WASM binary format
Fix: Incorrect offset calculation in PE parser
Update: Improve hex view performance
Docs: Add examples for Mach-O format

Questions?

If you have questions, feel free to:

• Open an issue for discussion
• Reach out to the maintainers

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.