Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (84 loc) · 3.61 KB

CONTRIBUTING.md

File metadata and controls

128 lines (84 loc) · 3.61 KB
Raw

Contributing to lstk

lstk is developed by the LocalStack team. You can read the source, build it, and fork it freely.

We do not accept pull requests from outside collaborators.

The way to participate is to open a well-formed issue. A reproducible bug report or a clearly explained feature request gives us the context we need to act.

Filing an issue

Open a new issue for a bug report or feature request.

For bug reports, include enough information for someone else to reproduce the problem without a follow-up.

For feature requests, lead with the problem rather than only a proposed implementation.

Why we don't accept outside pull requests

lstk's architecture and roadmap move quickly, and reviewing outside patches requires context and coordination we cannot currently offer fairly. An issue lets us validate the problem and decide on an approach before anyone spends time implementing it.

Development Setup

Prerequisites

  • Go 1.21+ (or latest stable)
  • Docker (for integration tests)
  • Make
  • pre-commit (for secret scanning hooks)

First-time setup

After cloning, install the pre-commit hooks:

pre-commit install

This sets up a local git hook that runs gitleaks before each commit to prevent accidentally committing secrets or credentials.

Building

make build              # Compiles to bin/lstk

Running Tests

make test               # Run unit tests (cmd/ and internal/) via gotestsum
make test-integration   # Run integration tests (rebuilds bin/lstk first, requires Docker)
make lint               # Run golangci-lint

To run a single integration test:

make test-integration RUN=TestStartCommandSucceedsWithValidToken

Code Style

  • Comments: only for non-obvious "why" decisions
  • Error handling: always check returned errors (except in tests)
  • No package-level global variables; use constructors and dependency injection
  • No direct stdout/stderr printing; use output.Sink for user output, log.Logger for diagnostics

Architecture

  • cmd/ — CLI wiring only (Cobra), no business logic
  • internal/ — all business logic:
    • container/ — emulator container handling
    • runtime/ — container runtime abstraction (Docker)
    • auth/ — authentication (env token, keyring, browser login)
    • config/ — Viper-based TOML config
    • output/ — event/sink system for CLI/TUI rendering
    • ui/ — Bubble Tea views
    • update/ — self-update logic
    • log/ — internal diagnostic logging

See CLAUDE.md for full architecture details.

Adding Features

New Commands

Use the skill:

/add-command <name>

This scaffolds a new CLI subcommand with proper wiring, domain logic, and tests.

New Output Events

Use the skill:

/add-event <EventName>

This adds a new typed event to the output/ event system.

New UI Components

Use the skill:

/add-component <name>

This scaffolds a new Bubble Tea TUI component.

Testing Guidelines

  • Prefer integration tests for most behavior
  • Unit tests for isolated logic where integration is impractical
  • When fixing a bug, always add an integration test that reproduces the scenario

Pull Requests for Collaborators

These steps are for authorized repository collaborators:

  1. Create a feature branch from main
  2. Run make lint and make test before submitting
  3. Review your own PR first — run /review-pr <number>
  4. Open a PR against main

Questions?

Check README.md for usage docs and CLAUDE.md for architecture.