CONTRIBUTING.md

Contributing to Version Guard

Thank you for your interest in contributing to Version Guard! This document provides guidelines and instructions for contributing.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

How to Contribute

Reporting Bugs

1. Check if the bug has already been reported in GitHub Issues
2. If not, create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs actual behavior
   • Version Guard version, Go version, OS
   • Relevant logs or error messages

Suggesting Features

1. Check GitHub Discussions for existing feature requests
2. Create a new discussion with:
   • Clear description of the feature
   • Use case and benefits
   • Potential implementation approach (if applicable)

Pull Requests

1. Fork the repository and create a feature branch:

   git checkout -b feature/my-new-feature

2. Make your changes:

   • Write clear, concise code
   • Follow existing code style and patterns
   • Add tests for new functionality
   • Update documentation as needed

3. Test your changes:

   make test          # Run all tests
   make lint          # Check code quality
   make build-all     # Verify build

4. Commit your changes:

   • Use clear, descriptive commit messages
   • Reference relevant issues (e.g., "Fix #123: Description")

5. Push and create a pull request:

   git push origin feature/my-new-feature

   Then create a PR on GitHub with:

   • Description of changes
   • Related issues
   • Testing performed

Development Setup

Prerequisites

• Go 1.24+
• Docker (for local Temporal)
• Make
• AWS CLI (for S3 snapshot testing)

Local Development

# Clone the repository
git clone https://github.com/block/Version-Guard.git
cd Version-Guard

# Install development tools
make setup

# Build binaries
make build-all

# Run tests
make test

# Start local Temporal server (in separate terminal)
make temporal

# Run the server with auto-reload
make dev

Code Style

• Go: Follow Effective Go and run gofmt
• Linting: Code must pass golangci-lint (run make lint)
• Imports: Use goimports for import formatting (run make fmt-imports)
• Tests: Write unit tests for new functionality (aim for >80% coverage)

Testing Guidelines

Unit Tests

• Place test files next to the code they test (foo.go → foo_test.go)
• Use table-driven tests where appropriate
• Mock external dependencies

Example:

func TestDetector_Detect(t *testing.T) {
    tests := []struct {
        name    string
        input   *types.Resource
        want    *types.Finding
        wantErr bool
    }{
        {
            name: "detects red status",
            // ...
        },
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // ...
        })
    }
}

Integration Tests

• Tag integration tests with // +build integration
• Require actual external dependencies (Wiz, AWS, etc.)
• Document setup requirements

Adding a New Resource Type

To add support for a new resource type:

1. Define the resource type in pkg/types/resource.go:

   const ResourceTypeYourResource ResourceType = "your-resource"

2. Create an inventory source in pkg/inventory/:

   // pkg/inventory/wiz/your_resource.go
   type YourResourceInventorySource struct { /* ... */ }

3. Create an EOL provider (or use existing):

   // pkg/eol/aws/your_resource.go or use endoflife.date

4. Create a detector in pkg/detector/your_resource/:

   // pkg/detector/your_resource/detector.go
   type Detector struct { /* ... */ }

5. Add tests for all components

6. Update documentation (README.md, ARCHITECTURE.md)

Project Structure

Version-Guard/
├── cmd/
│   ├── server/          # Main server binary
│   └── cli/             # CLI tool
├── pkg/
│   ├── types/           # Core data structures
│   ├── policy/          # Classification policies
│   ├── inventory/       # Inventory sources (Wiz, mock)
│   ├── eol/             # EOL data providers
│   ├── detector/        # Resource detectors
│   ├── store/           # Finding storage
│   ├── snapshot/        # S3 snapshot management
│   ├── workflow/        # Temporal workflows
│   ├── service/         # gRPC service
│   └── emitters/        # Emitter interfaces + examples
├── protos/              # Protocol Buffers
├── docs/                # Documentation
└── .github/             # GitHub workflows

Release Process

Releases are managed by maintainers:

1. Update version in relevant files
2. Update CHANGELOG.md
3. Create a git tag: git tag -a v1.0.0 -m "Release v1.0.0"
4. Push tag: git push origin v1.0.0
5. GitHub Actions will build and publish release artifacts

Questions?

• General questions: Use GitHub Discussions
• Bug reports: Use GitHub Issues
• Security issues: Email security@block.xyz

Thank you for contributing to Version Guard!