Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
368 lines (264 loc) · 7.17 KB

CONTRIBUTING.md

File metadata and controls

368 lines (264 loc) · 7.17 KB

Contributing to kubenow

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

Table of Contents

Code of Conduct

Be respectful, constructive, and professional in all interactions.

Getting Started

Prerequisites

  • Go ≥ 1.25
  • kubectl configured with access to a Kubernetes cluster (for testing)
  • make (for build automation)
  • git
  • golangci-lint (optional, for local linting)

Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/kubenow.git
cd kubenow

# Add upstream remote
git remote add upstream https://github.com/ppiankov/kubenow.git

Development Setup

1. Install Dependencies

make deps

This downloads all Go modules and tidies dependencies.

2. Build

make build

Binary will be created at bin/kubenow.

3. Run Tests

make test

4. Run Linter (Optional)

make lint

Note: If golangci-lint is not installed:

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | \
  sh -s -- -b $(go env GOPATH)/bin

Making Changes

Branching Strategy

Create a feature branch from main:

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

Branch naming conventions:

  • feature/* - New features
  • fix/* - Bug fixes
  • docs/* - Documentation updates
  • refactor/* - Code refactoring
  • test/* - Test improvements

Commit Messages

Follow Conventional Commits:

type: concise imperative statement

Lowercase after colon, no period. Max 72 chars.

Types: feat, fix, docs, refactor, test, chore, perf, ci, build

Examples:

feat: add requests-skew analysis command
fix: handle empty prometheus response
docs: update architecture diagram

Body (optional, separated by blank line) for WHY, not WHAT.

Testing

Unit Tests

# Run all tests
make test

# Run specific package tests
go test ./internal/analyzer -v

# Run with coverage
make test-coverage

Integration Tests

# Run integration tests (requires Kubernetes cluster)
go test ./test/integration -v

Test Guidelines

  • Write tests for new features
  • Maintain or improve code coverage
  • Use table-driven tests where appropriate
  • Mock external dependencies (Prometheus, Kubernetes API)

Example test structure:

func TestMyFeature(t *testing.T) {
    tests := []struct {
        name     string
        input    string
        expected string
    }{
        {"case1", "input1", "output1"},
        {"case2", "input2", "output2"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := MyFeature(tt.input)
            assert.Equal(t, tt.expected, result)
        })
    }
}

Submitting Changes

Before Submitting

  1. Run all checks:

    make check

  2. Ensure tests pass:

    make test

  3. Update documentation if needed

  4. Add or update tests for your changes

Create Pull Request

  1. Push your branch:

    git push origin feature/my-new-feature

  2. Open a Pull Request on GitHub

  3. Fill in the PR template:

    • Description of changes
    • Related issue numbers
    • Testing performed
    • Screenshots (if UI changes)

PR Review Process

  • CI checks must pass (tests, lint, build)
  • At least one approving review required
  • Maintainers may request changes
  • Be responsive to feedback

After Approval

  • Squash commits if requested
  • Maintainer will merge when ready

Code Style

Go Style Guide

Follow standard Go conventions:

  • Use gofmt for formatting
  • Follow Effective Go
  • Use meaningful variable names
  • Add comments for exported functions

Linter Configuration

We use golangci-lint with configuration in .golangci.yml.

Key rules:

  • Max line length: 140 characters
  • Max cyclomatic complexity: 15
  • Required error checking
  • No unused code

Running Formatters

# Format code
make fmt

# Run vet
make vet

Project Structure

kubenow/
├── cmd/
│   └── kubenow/          # Main entry point
├── internal/
│   ├── analyzer/         # Analysis logic (requests-skew, node-footprint)
│   ├── cli/              # CLI commands (Cobra)
│   ├── export/           # Export formats (JSON, Markdown, HTML)
│   ├── llm/              # LLM client
│   ├── metrics/          # Prometheus integration
│   ├── models/           # Data models
│   ├── prompt/           # LLM prompt templates
│   ├── result/           # Result rendering
│   ├── snapshot/         # Kubernetes snapshot collection
│   ├── util/             # Utilities
│   └── watch/            # Watch mode
├── test/
│   ├── fixtures/         # Test data
│   └── integration/      # Integration tests
├── docs/                 # Documentation
├── .github/workflows/    # CI/CD
├── Makefile              # Build automation
├── .golangci.yml         # Linter config
└── go.mod                # Go modules

Adding a New Command

  1. Create command file:

    # internal/cli/mycommand.go

  2. Implement command:

    package cli

import "github.com/spf13/cobra"

var myCmd = &cobra.Command{
    Use:   "mycommand",
    Short: "My command description",
    RunE:  runMyCommand,
}

func init() {
    rootCmd.AddCommand(myCmd)
    // Add flags
}

func runMyCommand(cmd *cobra.Command, args []string) error {
    // Implementation
    return nil
}

  3. Add tests:

    # internal/cli/mycommand_test.go

  4. Update documentation

Common Tasks

Adding a New Analyzer

  1. Create analyzer in internal/analyzer/
  2. Implement analyzer logic
  3. Create CLI command in internal/cli/
  4. Add unit tests
  5. Update README with examples

Adding Prometheus Queries

  1. Update internal/metrics/query.go
  2. Add query builder method
  3. Test with mock Prometheus
  4. Document query purpose

Modifying LLM Prompts

  1. Update internal/prompt/templates.go
  2. Test with local LLM
  3. Verify JSON response parsing
  4. Update result rendering if schema changes

Getting Help

Recognition

Contributors will be recognized in:

  • Release notes
  • GitHub contributors page
  • Changelog

Thank you for contributing to kubenow! 🙏