Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (167 loc) · 6.63 KB

CONTRIBUTING.md

File metadata and controls

226 lines (167 loc) · 6.63 KB

Contributing to hyperfleet-sentinel

Development Setup

Complete local environment setup including prerequisites, installation, and first run.

# 1. Clone the repository
git clone https://github.com/openshift-hyperfleet/hyperfleet-sentinel.git
cd hyperfleet-sentinel

# 2. Install prerequisites
# - Go 1.25 or later
# - Docker or Podman
# - Make
# - pre-commit

# 3. Generate OpenAPI client (required before any other commands)
make generate

# 4. Install dependencies
make download

# 5. Build the project
make build

# 6. Run tests to verify setup
make test

# 7. Install git hooks
make install-hooks

First-time setup notes:

  • The OpenAPI client code is not committed to git and must be generated locally via make generate
  • Generated code appears in pkg/api/openapi/ and must be regenerated after any spec updates
  • Integration tests require Docker/Podman for testcontainers (RabbitMQ, GCP Pub/Sub emulators)
  • make install-hooks installs pre-commit hooks configured in .pre-commit-config.yaml for commit message and code quality validation on every commit
  • See docs/testcontainers.md for Docker/Podman configuration
  • See docs/development.md for build, test, and local development
  • See docs/deployment.md for Helm deployment and configuration
  • See docs/sentinel-for-gke-dev.md for GKE dev deployment

Repository Structure

Overview of key directories and files - what's where and why.

hyperfleet-sentinel/
├── cmd/
│   └── sentinel/           # Main application entry point
├── internal/               # Private application code
│   ├── client/            # HyperFleet API client with retry logic
│   ├── config/            # Configuration loading and validation
│   ├── engine/            # Core polling and reconciliation engine
│   ├── health/            # Health and readiness probes
│   ├── publisher/         # CloudEvents publishing logic
│   └── sentinel/          # Main service orchestration
├── pkg/                   # Public library code
│   ├── api/openapi/       # Generated OpenAPI client (not committed)
│   └── metrics/           # Prometheus metrics definitions
├── test/
│   └── integration/       # Integration tests with testcontainers
├── charts/                # Helm chart for deployment
├── configs/               # Example configuration files
├── deployments/           # Kubernetes manifests and Grafana dashboards
├── openapi/               # OpenAPI client generation config
├── docs/                  # Additional documentation
├── Makefile               # Build automation and development tasks
├── README.md              # Getting started guide
└── CONTRIBUTING.md        # This file

Testing

How to run unit tests, integration tests, linting, and validation.

Unit Tests

# Run all unit tests (fast, no external dependencies)
make test

# Run unit tests with coverage
make test-coverage

# Run unit tests for a specific package
go test -v ./internal/config/

Integration Tests

# Run integration tests (requires Docker/Podman)
make test-integration

# Integration tests use testcontainers to spin up:
# - RabbitMQ broker
# - GCP Pub/Sub emulator

Linting and Quality Checks

# Run all verification checks (vet + format check)
make verify

# Run golangci-lint
make lint

# Check code formatting
make fmt-check

# Auto-format code
make fmt

# Run all quality gates (lint + all tests)
make test-all

Helm Chart Testing

# Lint and validate Helm chart
make test-helm

Chart Documentation

The Helm chart README is auto-generated by helm-docs from annotations in charts/values.yaml. Do not edit charts/README.md by hand — your changes will be overwritten.

# Regenerate the chart README after modifying values.yaml
make helm-docs

# Verify the README is up to date (CI runs this automatically)
make verify-helm-docs

When adding or modifying values in charts/values.yaml, annotate each key with a # -- comment directly above it:

# -- Number of sentinel replicas
replicaCount: 1

image:
  # -- Container image registry
  registry: quay.io

The verify-helm-docs check runs as part of make test-helm and will fail the PR if the README is out of date.

Common Development Tasks

Build commands, running locally, generating code, etc.

Building

# Clean build
make clean && make build

# Build container image
make image

# Build and push to registry
make image-push

# Build and push to personal Quay registry
QUAY_USER=myusername make image-dev

Running Locally

# Run with example configuration
./bin/sentinel serve --config configs/dev-example.yaml

# Run with custom broker configuration
BROKER_CONFIG_FILE=broker.yaml ./bin/sentinel serve --config configs/dev-example.yaml

# For detailed local deployment instructions, see docs/development.md
# For detailed GKE deployment instructions, see docs/sentinel-for-gke-dev.md

Code Generation

# Generate OpenAPI client from the pinned hyperfleet-api-spec module
make generate

# To upgrade the spec version, bump the module in go.mod first:
go get github.com/openshift-hyperfleet/hyperfleet-api-spec@vX.Y.Z
go mod tidy
make generate

# Clean generated code
make clean

Commit Standards

All commits must follow the HyperFleet commit message format:

HYPERFLEET-### - type: description

Optional longer description.

Co-Authored-By: Name <email@example.com>

Types: feat, fix, chore, docs, test, refactor

Examples:

  • HYPERFLEET-123 - feat: add support for nested payload fields
  • HYPERFLEET-456 - fix: handle nil pointer in status polling
  • HYPERFLEET-789 - chore: update hyperfleet-broker to v1.1.0

For detailed commit conventions, see the HyperFleet Architecture Repository.

Release Process

Releases are created manually via GitHub Releases and follow Semantic Versioning.

  1. Update CHANGELOG.md - move [Unreleased] items to new version section
  2. Create and push version tag: git tag v0.x.y && git push origin v0.x.y
  3. Create GitHub Release with tag, referencing CHANGELOG entries
  4. Container images are built and pushed to quay.io/openshift-hyperfleet/sentinel:v0.x.y
  5. Update hyperfleet-chart umbrella chart with new version

Deployment is managed via the hyperfleet-chart umbrella Helm chart which includes Sentinel as a subchart.