CONTRIBUTING.md

Contributing to HyperFleet Adapter

Thank you for your interest in contributing to HyperFleet Adapter! This document provides guidelines and instructions for contributing to the project.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Code Style
• Testing
• Submitting Changes
• Pull Request Process

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

1. Fork the repository on GitHub

2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/hyperfleet-adapter.git
   cd hyperfleet-adapter

3. Add the upstream remote:

   git remote add upstream https://github.com/openshift-hyperfleet/hyperfleet-adapter.git

4. Create a branch for your changes:

   git checkout -b your-feature-branch

Development Setup

Prerequisites

• Go 1.24 or later
• Docker (for building Docker images)
• golangci-lint (for linting)
• make (for running Makefile targets)

Installing Dependencies

1. Install Go dependencies:

   make tidy

2. Install golangci-lint (if not already installed):

   go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Building the Project

# Build the binary
make build

# The binary will be created at: bin/hyperfleet-adapter

Running Tests

# Run unit tests
make test

# Run integration tests
make test-integration

# Run all tests
make test-all

# Run tests with coverage
make test-coverage

Linting

# Run linter
make lint

# Format code
make fmt

Making Changes

Branch Naming

Use descriptive branch names that indicate the type of change:

• feature/your-feature-name - For new features
• fix/your-fix-name - For bug fixes
• docs/your-doc-update - For documentation changes
• refactor/your-refactor-name - For code refactoring

Commit Messages

Follow these guidelines for commit messages:

1. Use the present tense ("Add feature" not "Added feature")
2. Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
3. Limit the first line to 72 characters or less
4. Reference issues and pull requests liberally after the first line
5. Consider starting the commit message with an applicable emoji:
   • 🎨 :art: - Improving structure / format of the code
   • 🐛 :bug: - Fixing a bug
   • 📝 :memo: - Writing docs
   • ✨ :sparkles: - Introducing new features
   • ♻️ :recycle: - Refactoring code
   • ✅ :white_check_mark: - Adding tests
   • 🔧 :wrench: - Changing configuration

Example:

✨ Add operation ID middleware for request tracing

- Implement OperationIDMiddleware to generate unique operation IDs
- Add GetOperationID and WithOpID helper functions
- Update logger to include operation ID in log context

Fixes #123

Code Style

Go Code Style

• Follow the Effective Go guidelines
• Use gofmt or goimports to format code
• Run make fmt before committing

General Guidelines

1. Keep functions small and focused - Each function should do one thing well
2. Use meaningful variable names - Avoid abbreviations unless they're widely understood
3. Add comments for exported functions, types, and packages
4. Handle errors explicitly - Don't ignore errors
5. Use context.Context for cancellation and timeouts in long-running operations

Package Organization

• cmd/ - Main applications for this project
• pkg/ - Library code that can be imported by other projects
• test/ - Integration tests and test utilities
• data/ - Configuration templates and data files
• charts/ - Helm chart templates

Testing

Unit Tests

• Write unit tests for all new functionality
• Use table-driven tests when testing multiple scenarios
• Run tests before submitting: make test

Integration Tests

• Write integration tests for components that interact with external systems
• Use testcontainers for testing with real dependencies (e.g., databases, message brokers)
• Run integration tests: make test-integration

Test Guidelines

1. Test names should be descriptive: TestFunctionName_Scenario_ExpectedBehavior
2. Use subtests for multiple test cases:

   func TestFunction(t *testing.T) {
       tests := []struct {
           name string
           // ... test cases
       }{
           // ... test data
       }
       
       for _, tt := range tests {
           t.Run(tt.name, func(t *testing.T) {
               // test implementation
           })
       }
   }

3. Clean up resources in tests (use defer or t.Cleanup())

Submitting Changes

Before Submitting

1. Update your branch with the latest changes from upstream:

   git fetch upstream
   git rebase upstream/main

2. Run all checks:

   make verify  # Runs fmt-check and vet

3. Ensure all tests pass:

   make test-all

4. Check for linting errors:

   make lint

5. Format your code:

   make fmt

Pull Request Process

1. Push your changes to your fork:

   git push origin your-feature-branch

2. Create a Pull Request on GitHub:

   • Use a clear and descriptive title
   • Reference any related issues in the description
   • Describe what changes you made and why
   • Include screenshots or examples if applicable

3. PR Checklist:

   • Code follows the project's style guidelines
   • Self-review completed
   • Comments added for complex code
   • Documentation updated (if needed)
   • Tests added/updated
   • All tests pass (make test-all)
   • Linting passes (make lint)
   • No merge conflicts with main branch

PR Description Template

## Description
Brief description of the changes

## Related Issues
Fixes #123
Related to #456

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

## Testing
Describe the tests you ran and their results

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated

Code Review

• All PRs require at least one approval before merging
• Address review comments promptly
• Be respectful and constructive in reviews
• Ask questions if something is unclear

Questions?

If you have questions or need help:

1. Check existing issues and pull requests
2. Open a new issue with the question label
3. Reach out to maintainers