kportal/CONTRIBUTING.md

Contributing to kportal

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

Code of Conduct

Be respectful and constructive. We're all here to build something awesome together.

How to Contribute

Reporting Bugs

Before creating a bug report, please check if the issue already exists. When creating a bug report, include:

• Clear title and description
• Steps to reproduce
• Expected behavior
• Actual behavior
• Screenshots (if applicable)
• Environment details (OS, kportal version, Go version, Kubernetes version)
• Configuration file (sanitized)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

• Clear title and description
• Use case - why this enhancement would be useful
• Possible implementation (optional)
• Alternative solutions (if any)

Pull Requests

1. Fork the repository

   git clone https://github.com/yourusername/kportal.git
   cd kportal
   

2. Create a feature branch

   git checkout -b feature/amazing-feature
   

3. Make your changes

   • Write clear, readable code
   • Follow Go conventions and best practices
   • Add tests for new functionality
   • Update documentation as needed

4. Run quality checks

   make all  # Runs fmt, vet, staticcheck, test, build
   

5. Commit your changes

   Follow semantic commit messages:

   git commit -m "feat: add amazing feature"
   

6. Push to your fork

   git push origin feature/amazing-feature
   

7. Open a Pull Request

   • Provide a clear description of the changes
   • Reference any related issues
   • Ensure all CI checks pass

Development Setup

Prerequisites

• Go 1.23 or higher
• Access to a Kubernetes cluster
• kubectl configured

Building

# Install development tools
make install-tools

# Build the binary
make build

# Run tests
make test

# Run with race detection
go test -race ./...

# Check code quality
make vet
make staticcheck
make fmt

Running Locally

# Build and install
make build
make install

# Run with your config
kportal -c .kportal.yaml

# Run in verbose mode
kportal -v

Commit Message Format

We use semantic commit messages for automatic version generation:

Commit Types

• feat - New feature (bumps minor version)
• fix - Bug fix (bumps patch version)
• docs - Documentation only changes (bumps patch version)
• style - Code style changes (formatting, missing semi colons, etc.)
• refactor - Code refactoring
• test - Adding or updating tests
• chore - Maintenance tasks
• breaking - Breaking changes (bumps major version)

Format

<type>: <description>

[optional body]

[optional footer]

Examples

# Feature
git commit -m "feat: add health check grace period"

# Bug fix
git commit -m "fix: resolve port conflict detection bug"

# Breaking change
git commit -m "breaking: change config file format

BREAKING CHANGE: Config file format has changed from JSON to YAML.
Migration tool available with --convert flag."

# Documentation
git commit -m "docs: update installation instructions"

Project Structure

kportal/
├── cmd/kportal/              # Main application entry point
├── internal/
│   ├── config/               # Configuration parsing and validation
│   ├── forward/              # Port-forward manager and workers
│   ├── healthcheck/          # Health monitoring system
│   ├── k8s/                  # Kubernetes client wrapper
│   ├── retry/                # Retry logic with backoff
│   ├── ui/                   # Terminal UI implementations
│   └── converter/            # kftray JSON converter
├── Formula/                  # Homebrew formula
├── .github/workflows/        # CI/CD pipelines
└── docs/                     # Documentation and GitHub Pages

Coding Guidelines

Go Style

• Follow Effective Go
• Use gofmt for formatting
• Keep functions small and focused
• Write descriptive variable names
• Add comments for exported functions
• Handle errors explicitly

Testing

• Write tests for new functionality
• Aim for meaningful test coverage
• Use table-driven tests where appropriate
• Mock external dependencies
• Test edge cases and error conditions

Example test:

func TestForwardWorker_Start(t *testing.T) {
    tests := []struct {
        name    string
        forward config.Forward
        wantErr bool
    }{
        {
            name: "valid pod forward",
            forward: config.Forward{
                Resource:  "pod/test",
                Port:      8080,
                LocalPort: 8080,
            },
            wantErr: false,
        },
        // Add more test cases
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}

Documentation

• Update README.md for user-facing changes
• Add code comments for complex logic
• Update CHANGELOG.md following Keep a Changelog
• Document new configuration options
• Add examples for new features

Release Process

Releases are automated via GitHub Actions:

1. Version is determined automatically by semver-gen based on commit messages
2. Create a tag following semantic versioning:

   git tag -a v0.2.0 -m "Release version 0.2.0"
   git push origin v0.2.0
   

3. GitHub Actions will:
   • Build binaries for all platforms
   • Create GitHub release
   • Update Homebrew formula
   • Generate release notes

Getting Help

• Questions? Open a GitHub Discussion
• Bug or feature request? Open a GitHub Issue
• Want to chat? Reach out on GitHub

Recognition

Contributors will be recognized in:

• GitHub's contributor graph
• Release notes
• README.md (for significant contributions)

Thank you for contributing to kportal! 🎉