Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
175 lines (126 loc) · 4.53 KB

DEVELOPMENT.md

File metadata and controls

175 lines (126 loc) · 4.53 KB
Raw

Development Guide

Prerequisites

Required Tools

  • Go: Go 1.26.4 or later (matches the go directive in go.mod; required for the tool directive and modern syntax)
  • gox: Cross-platform Go compilation tool (required for make release)
  • mockgen: Provided as a go.mod tool dependency, so no separate install is needed (see Code Generation)

Installing gox

go install github.com/mitchellh/gox@latest

PATH Configuration

Ensure your Go bin directory is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

First-Time Setup

After cloning the repository:

  1. Install dependencies:

    go mod download

  2. Sync and verify dependencies:

    go mod tidy

  3. Verify setup by running tests:

    make test

Building

Local Development Build

Build a binary for your current platform:

make lifecycled

This creates a lifecycled binary in the current directory.

Testing

Run tests, formatting, and vet checks:

make test

This will:

  • Format code with gofmt
  • Run go vet for static analysis
  • Run all tests with race detection

Clean Build Artifacts

make clean

Release Process

Building Release Binaries

The current release process uses gox for cross-platform compilation:

make release

This builds binaries for the following platforms:

  • freebsd/amd64
  • linux/386
  • linux/aarch64
  • linux/amd64
  • linux/arm64
  • windows/amd64

Output Location: All binaries are placed in the build/ directory with the naming pattern:

build/lifecycled-{OS}-{Arch}

Version Injection

The build process automatically injects version information from git tags:

VERSION=$(git describe --tags --candidates=1 --dirty 2>/dev/null || echo "dev")

This version is embedded into the binary using Go build flags:

-ldflags="-s -w -X main.Version=$(VERSION)"

Manual Release Steps

  1. Create and push a git tag:

    git tag v1.2.3
git push --tags

  2. Build release binaries:

    make release

  3. Create GitHub release:

    • Navigate to the GitHub repository
    • Create a new release
    • Select the tag created in step 1
    • Set the Release title to the tag (v1.2.3)
    • Set the Previous tag to the tag of the most previous release
    • Click Generate Release Notes

  4. Upload binaries:

    • Manually upload all binaries from the build/ directory to the GitHub release

  5. Publish the release

Code Generation

The project uses code generation to create mock implementations for testing. If you make changes to interfaces or need to regenerate mocks:

make generate

This runs go generate ./..., which invokes go tool mockgen to regenerate the mock files in the mocks/ directory. mockgen is pinned as a tool dependency in go.mod (go.uber.org/mock, the actively maintained fork of github.com/golang/mock), so generation is reproducible without installing mockgen separately.

CI verifies the committed mocks stay in sync by running go generate ./... followed by git diff --exit-code, so regenerate and commit the result after changing any interface. CI also runs golangci-lint (config in .golangci.yml) and go test -race.

Generated files:

  • mocks/mock_autoscaling_client.go
  • mocks/mock_sns_client.go
  • mocks/mock_sqs_client.go

Project Structure

.
├── cmd/
│   └── lifecycled/        # Main application entry point
├── mocks/                 # Generated mock implementations for testing
├── tools/                 # Additional tools (e.g., lifecycled-queue-cleaner)
├── terraform/             # Terraform configurations
├── init/                  # Initialization scripts
├── build/                 # Build output directory (created by make release)
├── .buildkite/           # Buildkite CI configuration
└── .github/              # GitHub workflows and configuration

Development Notes

  • The project uses Go modules (GO111MODULE=on)
  • After cloning or when dependencies change, run go mod tidy to sync dependencies
  • Version information is derived from git tags
  • Mock generation uses go.uber.org/mock (the actively maintained fork of gomock), not the deprecated github.com/golang/mock
  • Generated mock files should not be manually edited; regenerate them using make generate
  • The project requires Go 1.26.4 or later (the go directive in go.mod); the tool directive needs at least Go 1.24