Skip to content

Latest commit

 

History

History
445 lines (315 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

445 lines (315 loc) · 11.6 KB

Contributing to Team Operator

This guide covers development setup and contribution workflow for the Team Operator project.

Table of Contents

Project Overview

Team Operator is a Kubernetes operator built with Kubebuilder that automates deployment, configuration, and management of Posit Team products (Workbench, Connect, Package Manager, and Chronicle) within Kubernetes clusters.

Note: This repository is under active development and is not yet ready for production use.

Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

  • Go 1.25+ (version specified in go.mod)
  • Docker (for building container images)
  • kubectl (configured to access a Kubernetes cluster)
  • Kubernetes cluster (1.29+ for testing; k3d works well for local development)
  • Just command runner (brew install just on macOS, or see installation guide)
  • Helm (for chart development and testing)

On macOS, you may also need gsed for some Makefile targets:

brew install gnu-sed

Cloning the Repository

git clone https://github.com/posit-dev/team-operator.git
cd team-operator

Installing Dependencies

just deps

This also installs git hooks that run automatically on commit.

Git Hooks

Pre-commit hooks run automatically when you commit:

Hook Triggers On What It Does
format All commits Formats Go code
vet .go files Static analysis
mgenerate api/**/*.go Regenerates CRDs and manifests
helm-generate config/** Regenerates Helm chart from kustomize
helm-lint dist/chart/** Lints Helm chart
helm-template dist/chart/** Verifies templates render

If a hook fails, the commit is blocked. Fix the issue, stage any generated files, and commit again.

# Run hooks manually on all files
uvx pre-commit run --all-files

# Skip all hooks
git commit --no-verify -m "message"

# Skip specific hooks only
SKIP=vet git commit -m "message"
SKIP=vet,mgenerate git commit -m "message"

Building the Operator

just build

This compiles the operator binary to ./bin/team-operator.

Running Locally

To run the operator against your current Kubernetes context:

just run

For development with a local Kubernetes cluster:

# Create a k3d cluster
just k3d-up

# Install CRDs
just crds

# Run the operator
just run

Running Tests

just test

For tests with envtest (Kubebuilder test framework):

just mtest

Project Structure

Directory Description
api/ Kubernetes API/CRD definitions
cmd/ Main operator entry point
internal/ Core operator logic and controllers
internal/controller/ Reconciliation controllers for each resource type
config/ Kubernetes manifests and Kustomize configurations
dist/chart/ Helm chart for deployment
flightdeck/ Landing page dashboard component
client-go/ Generated Kubernetes client code
pkg/ Shared packages
openapi/ Generated OpenAPI specifications
hack/ Build and development scripts

Making Changes

Branching Strategy

  1. Create a feature branch from main:

    git checkout main
git pull origin main
git checkout -b your-feature-name

  2. Use descriptive branch names with hyphens (avoid slashes):

    • Good: add-workbench-scaling, fix-database-connection
    • Avoid: feature/workbench, fix/db

PR Title Conventions (Required)

We use Conventional Commits and squash merging. Your PR title becomes the commit message and must follow this format:

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

Important: PR titles are validated by CI. PRs with non-conforming titles cannot be merged. This is enforced because semantic-release uses commit messages to determine version bumps.

Types:

  • feat: - New feature (triggers minor version bump)
  • fix: - Bug fix (triggers patch version bump)
  • docs: - Documentation only changes
  • refactor: - Code change that neither fixes a bug nor adds a feature
  • test: - Adding or correcting tests
  • build: - Changes to build system or dependencies
  • ci: - Changes to CI configuration
  • chore: - Other changes that don't modify src or test files
  • perf: - Performance improvements
  • style: - Code style changes (formatting, etc.)
  • revert: - Reverts a previous commit

Breaking changes: Add ! after the type (e.g., feat!:) or include BREAKING CHANGE: in the PR body. This triggers a major version bump.

Examples:

feat(connect): add support for custom resource limits
fix(workbench): resolve database connection timeout
docs: update installation instructions
refactor(controller): simplify reconciliation logic
feat!: change API response format

Code Style Guidelines

  1. Run formatters before committing:

    just format

    Or using make:

    make fmt

  2. Run linting:

    go vet ./...

  3. Follow existing patterns. New code should match the codebase.

  4. Keep functions focused. Each function should do one thing well.

  5. Use descriptive names. Names should reveal intent.

Adding New CRD Fields

When adding new fields to Custom Resource Definitions:

  1. Update the API types in api/:

    • Add the new field with appropriate JSON tags and Kubebuilder annotations
    • Include validation rules where appropriate

  2. Regenerate manifests:

    just mgenerate

  3. Update controller logic in internal/controller/ if needed.

  4. Add tests for the new functionality.

  5. Update Helm chart in dist/chart/ if the change affects deployment.

Example of adding a new field:

// +kubebuilder:validation:Optional
// +kubebuilder:default:=1
// Replicas is the number of instances to deploy
Replicas *int32 `json:"replicas,omitempty"`

Testing

Unit Tests

Run all unit tests:

just test

Or run Go tests directly:

go test -v ./...

Running Specific Tests

To run tests for a specific package:

go test -v ./internal/controller/...

To run a specific test:

go test -v ./internal/controller/... -run TestReconcile

Integration Tests with envtest

The project uses Kubebuilder's envtest for integration testing:

just mtest

This sets up a local Kubernetes API server for testing without requiring a full cluster.

Helm Chart Testing

# Lint the chart
just helm-lint

# Render templates locally (useful for debugging)
just helm-template

Coverage Reports

After running tests, view coverage:

go tool cover -func coverage.out

Pull Request Process

Before Submitting

  1. Ensure all tests pass:

    just test

  2. Format your code:

    just format

  3. Verify no uncommitted changes from generation:

    git diff --exit-code

  4. Lint the Helm chart:

    just helm-lint

PR Description

Include the following in your PR description:

  1. Summary: What does this PR do?
  2. Motivation: Why is this change needed?
  3. Testing: How was this tested?
  4. Breaking changes: Does this introduce any breaking changes?
  5. Related issues: Link to any related GitHub issues

CI Checks

The following checks must pass:

  • PR Title Check: Title must follow conventional commit format (see above)
  • Build: The operator must compile successfully
  • Unit tests: All tests must pass
  • Kustomize: Kustomization must build without errors
  • Helm lint: Chart must pass linting
  • Helm template: Templates must render correctly
  • No diff: Generated files must be committed

Merging

This repository uses squash and merge. Your PR title becomes the final commit message on main. The PR title format is enforced because semantic-release analyzes commit messages to determine version bumps.

Review Expectations

  • PRs require at least one approval before merging
  • Address all review comments or explain disagreements
  • Keep PRs focused. Smaller PRs are easier to review.
  • Respond to feedback promptly

Code Review Guidelines

We follow specific guidelines for code review. For detailed review standards, see .claude/review-guidelines.md.

Core Principles

  • Simplicity: Prefer explicit over clever
  • Maintainability: Follow existing patterns in the codebase
  • Security: Extra scrutiny for credential handling, RBAC, and network operations

Review Checklist by Area

API Changes (api/):

  • Kubebuilder annotations are correct
  • New fields have sensible defaults
  • Validation rules are present
  • Breaking changes have migration strategy

Controller Changes (internal/controller/):

  • Reconciliation is idempotent
  • Error handling reports status correctly
  • Config flows from Site -> Product correctly
  • Both unit and integration tests exist

Helm Chart (dist/chart/):

  • Values have sensible defaults
  • Templates render correctly
  • RBAC permissions are minimal
  • CRDs are up to date

Flightdeck (flightdeck/):

  • Go templates render correctly
  • Static assets are properly served
  • Configuration options are documented

What NOT to Comment On

  • Style issues handled by formatters (run make fmt)
  • Personal preferences without clear benefit
  • Theoretical concerns without concrete impact

Releasing

Releases are automated via semantic-release when commits are merged to main. Version bumps are determined by conventional commit prefixes:

  • fix: → patch (1.0.0 → 1.0.1)
  • feat: → minor (1.0.0 → 1.1.0)
  • feat!: or BREAKING CHANGE: → major (1.0.0 → 2.0.0)

The release workflow updates the changelog, tags the release, publishes the Helm chart to GHCR, and notifies downstream repos.

To manually trigger a release: gh workflow run release.yml

roborev Code Review

This repo uses roborev for continuous AI-assisted code review. roborev runs automatically on each commit and posts review feedback to pull requests.

To enable it locally, install the commit hook into your copy of the repo:

roborev install-hook

Once installed, roborev will run after each git commit and submit a review for any open PR associated with your branch.

Getting Help

If you have questions:

  1. Check existing documentation: README.md, this guide, and inline code comments
  2. Search existing issues: Your question may have been answered
  3. Open an issue: For bugs, feature requests, or questions
  4. Contact Posit: For production use inquiries, contact Posit

Quick Reference

Task Command
Build just build
Test just test
Run locally just run
Format code just format
Regenerate manifests just mgenerate
Install CRDs just crds
Helm lint just helm-lint
Helm template just helm-template
Helm install just helm-install
Create k3d cluster just k3d-up
Delete k3d cluster just k3d-down

Thank you for contributing to Team Operator!