Contributing

Here’s how to work on SwarmCracker.

Setup

Prerequisites

Go 1.26+
Git
Make
golangci-lint (for linting)

Setup

git clone https://github.com/restuhaqza/SwarmCracker
cd SwarmCracker
go mod download
make all

Repo Structure

cmd/
├── swarmcracker/    # Main CLI wrapper
├── swarmctl/        # Direct SwarmKit commands
├── swarmd-firecracker/  # Daemon

pkg/
├── executor/        # SwarmKit task → VM config
├── network/         # Bridges, TAP, VXLAN
├── discovery/       # Consul
├── swarmkit/        # SwarmKit glue
├── image/           # OCI extraction
├── lifecycle/       # VM start/stop
├── jailer/          # Security
├── storage/         # Volumes, secrets
├── snapshot/        # State snapshots
├── metrics/         # Prometheus
├── types/           # Shared types

docs/                # User + dev docs
infrastructure/      # Ansible deployment
test-automation/     # tests + multi-node lab (test-automation/multinode/)

Code Style

Go

Follow Effective Go. Run golangci-lint before submitting.

Commits

Conventional commits:

feat(executor): add snapshot restore
fix(network): VXLAN FDB race condition
docs(cli): document new flags

Types: feat, fix, docs, refactor, test, chore, perf Scopes: executor, network, discovery, jailer, storage, cli

Testing

# Everything
make test

# One package
go test ./pkg/network/...

# Coverage
go test -cover ./pkg/executor/...

Integration / E2E Tests

The blessed development path is the Go E2E suite:

make test-e2e

For a real multi-node cluster (microVMs scheduled across nodes over the VXLAN overlay), use the single-host lab:

sudo test-automation/multinode/cluster-lab.sh up 2
sudo test-automation/multinode/cluster-lab.sh test

Pull Requests

Fork it
Branch for your change
Write code + tests
make lint && make test
Push and open PR

Describe what you changed and why. If it fixes an issue, mention the number.

Before Submitting

Tests pass
Lint clean
No secrets in code (tokens, keys)
Documentation updated if needed

Questions

Open an issue or ask in discussions.

make all           # Build all binaries
make test          # Run tests
make lint          # Run linter
make clean         # Clean artifacts
make install       # Install binaries to $GOPATH/bin

IDE Setup

VS Code

{
  "go.toolsManagement.autoUpdate": true,
  "go.lintTool": "golangci-lint",
  "go.lintOnSave": "package"
}

GoLand

Enable golangci-lint
Configure Go 1.26 SDK

Troubleshooting

Build Fails

# Check Go version
go version  # Must be 1.26+

# Clear module cache
go clean -modcache

# Re-download dependencies
go mod download

Lint Errors

# Run lint with details
golangci-lint run ./pkg/...

# Fix auto-fixable issues
golangci-lint run --fix

Test Fails

# Run with verbose output
go test -v ./pkg/executor/...

# Check for race conditions
go test -race ./pkg/...

External Resources

See Also: Testing Overview | Architecture