Contributing to kubefwd

Thank you for your interest in contributing to kubefwd!

Pull Request Policy

We welcome pull requests for:

• Bug fixes - Fixing issues and errors
• Tests - Improving test coverage
• Documentation - Clarifying usage, fixing typos, adding examples
• Stability improvements - Performance, error handling, compatibility

Note: We are not currently accepting new feature PRs. Feature development is limited to maintainers.

Development Setup

Prerequisites

• Go 1.21 or later
• Access to a Kubernetes cluster for testing
• kubectl configured with cluster access

Building

# Clone the repository
git clone https://github.com/txn2/kubefwd.git
cd kubefwd

# Build
go build -o kubefwd ./cmd/kubefwd/kubefwd.go

# Build with version
go build -ldflags "-X main.Version=dev" -o kubefwd ./cmd/kubefwd/kubefwd.go

Running Tests

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific package tests
go test -v ./pkg/fwdport

# Run with coverage
go test -cover ./...

Running Locally

# Requires sudo for network interface and hosts file access
sudo -E ./kubefwd svc -n default --tui

# With debug logging
sudo -E ./kubefwd svc -n default --tui -v

Code Style

Go Conventions

• Follow standard Go formatting (gofmt)
• Use meaningful variable names
• Add comments for exported functions
• Handle errors explicitly

Project Conventions

• Use logrus for logging
• Use mutex for concurrent access to shared state
• Prefer channels for goroutine communication
• Follow existing patterns in the codebase

Running Linters

# Format code
go fmt ./...

# Vet for issues
go vet ./...

# If golangci-lint is installed
golangci-lint run

Making Changes

Before You Start

1. Check existing issues and PRs for similar work
2. For non-trivial changes, open an issue first to discuss
3. Ensure you understand the scope of your change

Development Process

1. Fork the repository
2. Create a feature branch: git checkout -b fix/issue-description
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: go test ./...
6. Commit with clear messages

Commit Messages

Use clear, descriptive commit messages:

Fix: Handle pod deletion during port forward

- Add check for nil channel before send
- Improve error message for connection failures
- Add test for pod deletion scenario

Pull Request Guidelines

1. Title: Clear description of the change
2. Description: Explain what and why, not just what
3. Tests: Include tests for bug fixes and new behavior
4. Documentation: Update docs if behavior changes
5. Size: Keep PRs focused; split large changes

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] Test improvement
- [ ] Documentation update
- [ ] Stability/performance improvement

## Testing
How was this tested?

## Checklist
- [ ] Tests pass locally
- [ ] Code follows project style
- [ ] Documentation updated (if applicable)

Testing

Unit Tests

• Test individual functions and methods
• Use table-driven tests where appropriate
• Mock external dependencies

Integration Tests

Located in test/integration/:

# Run integration tests (requires cluster)
sudo -E go test -tags=integration -v ./test/integration/

Test Coverage

We aim to maintain and improve test coverage:

# View coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Reporting Issues

Bug Reports

Include:

• kubefwd version (kubefwd version)
• Kubernetes version (kubectl version)
• Operating system and version
• Steps to reproduce
• Expected vs actual behavior
• Verbose output if applicable (-v flag)

Security Issues

For security vulnerabilities, please see SECURITY.md.

Code of Conduct

Please review our Code of Conduct before contributing.

Questions?

• Open a GitHub issue for questions
• Check existing documentation in the docs/ directory

License

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