# Contributing to KubeBrowse

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

# Table of Contents

Contributing to KubeBrowse
- Table of Contents
- Code of Conduct
- Getting Started
  - Development Environment Setup
  - Troubleshooting Common Issues
    - Go Version Mismatch
  - Project Structure
- Development Workflow
  - Branching Strategy
  - Commit Guidelines
    - Conventional Commits Format
    - DCO Sign-off Requirement
    - Example Commit
  - Pre-commit Hooks
- Pull Requests
  - PR Process
  - PR Requirements
- Coding Standards
  - Go Guidelines
  - Testing
  - Documentation
- Release Process

# Code of Conduct

We are committed to fostering a welcoming community. Please read and adhere to our Code of Conduct in all interactions.

# Getting Started

# Development Environment Setup

Fork and clone the repository

git clone https://github.com/browsersec/KubeBrowse.git
cd KubeBrowse

Set up the development environment

# Install dependencies and Git hooks
make setup

Run the application
```
make run
```
Access the application
- Open a browser and navigate to http://localhost:4567/connect

# Troubleshooting Common Issues

# Go Version Mismatch

If you encounter errors like compile: version "go1.24.0" does not match go tool version "go1.24.3", follow these steps:

Check your Go version
```
go version
```
Clean the Go module cache
```
go clean -modcache
```
Clean the Go build cache
```
go clean -cache
```
Reset the build system
```
rm -rf $GOPATH/pkg/mod/cache/build
```

Install or update to a consistent Go version

Using Go's official installation:

# Download the latest version
wget https://go.dev/dl/go1.24.3.linux-amd64.tar.gz

# Remove old installation (if needed)
sudo rm -rf /usr/local/go

# Install the new version
sudo tar -C /usr/local -xzf go1.24.3.linux-amd64.tar.gz

Or using a version manager like asdf:

asdf install golang 1.24.3
asdf global golang 1.24.3

Check your environment variables

Ensure your PATH and GOROOT are set correctly:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export GOROOT=/usr/local/go
export PATH=$GOROOT/bin:$PATH

Regenerate the Go modules
```
go mod tidy
```

# Project Structure

/cmd/guac/ - Main application entry point
/utils/ - Utility functions
/certs/ - Certificate files for TLS
/.githooks/ - Git hooks for development

# Development Workflow

# Branching Strategy

main - Stable branch containing the latest release
dev - Development branch for integrating features
Feature branches should be created from dev and named using the format: feature/short-description or fix/issue-description

# Commit Guidelines

We follow Conventional Commits for commit messages and require Developer Certificate of Origin (DCO) sign-off for all contributions.

# Conventional Commits Format

<type>(<scope>): <description>

<body>

<footer>

Types include:

feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code changes that neither fix bugs nor add features
test: Adding or modifying tests
chore: Changes to the build process or auxiliary tools

# DCO Sign-off Requirement

All commits must include a Signed-off-by line to certify that you have the right to submit the code under the project's license. This is required by the Developer Certificate of Origin.

To sign off your commits automatically:

# Configure git to always sign off commits (recommended)
git config --global format.signoff true

# Or use the -s flag for individual commits
git commit -s -m "feat(api): add new authentication endpoint"

To sign off existing commits:

# Sign off the last commit
git commit --amend --signoff

# Sign off multiple commits using interactive rebase
git rebase --signoff HEAD~<number-of-commits>

# Force push to update the PR
git push --force-with-lease

The sign-off line should look like:

Signed-off-by: Your Name <your.email@example.com>

# Example Commit

feat(api): add endpoint for user authentication

- Implement JWT token generation
- Add middleware for token validation

Fixes #123

Signed-off-by: John Doe <john.doe@example.com>

# Pre-commit Hooks

This project uses Lefthook for managing Git hooks to ensure code quality. The pre-commit hook checks:

Code formatting
Static analysis
Linting
Tests
Potential secrets

Install the hooks with:

make hooks

You can manually run the pre-commit checks:

# Check only staged files
make lint

# Check all files in the repository
make lint-all

If Lefthook is not found, you'll be prompted to install it. Lefthook hooks are automatically installed when you run make setup.

# Pull Requests

# PR Process

Create a new branch from dev
Implement your changes
Ensure tests pass and code meets quality standards
Push your branch and create a pull request against dev
Address any feedback from reviewers

# PR Requirements

PRs must have a clear description of changes
All tests must pass
Code must be properly formatted
Documentation must be updated if necessary
Changes should be covered by tests

# Coding Standards

# Go Guidelines

Follow the Go Code Review Comments
Use the standard Go formatting (gofmt)
Write idiomatic Go code
Keep functions small and focused
Add comments for exported functions, types, and packages

# Testing

Write tests for all new features and bug fixes
Aim for high test coverage, especially for critical paths
Use table-driven tests when appropriate
Run tests with make test

# Documentation

Document all exported functions, types, and packages
Update the README.md if adding new features or changing existing functionality
Add examples for complex features

# Release Process

Create a release branch from dev
Update version information
Run comprehensive tests
Merge to main once approved
Tag the release with the version number
Update documentation with release notes

Thank you for contributing to KubeBrowse!