Contributing

This guide is for developers who want to contribute to apt-bundle or understand its internals.

Project Structure

apt-bundle/
├── cmd/
│   └── apt-bundle/       # Main entry point
├── internal/
│   ├── aptfile/          # Aptfile parsing
│   ├── commands/         # CLI commands (install, dump, check)
│   ├── apt/              # APT interactions
│   └── config/           # Configuration
├── docs/                 # Documentation
├── Makefile              # Build automation
└── go.mod                # Go module definition

Prerequisites

Go 1.21 or later
Debian/Ubuntu-based system (for testing)
make (for build automation)

Building

Build the Binary

make build

The binary will be created at build/apt-bundle.

Install Locally

sudo make install

This installs to /usr/local/bin/apt-bundle by default. You can customize:

INSTALL_DIR=$HOME/.local/bin USE_SUDO="" make install

Build Options

The Makefile uses the following build flags:

CGO_ENABLED=0: Pure Go compilation (no C dependencies)
-ldflags="-s -w": Strip debug symbols for smaller binary size

Development Workflow

Format Code

make fmt

This runs go fmt ./... to format all Go code.

Run Static Analysis

make vet

This runs go vet ./... to catch common errors.

Run Linter

make lint

This runs golangci-lint for comprehensive code analysis.

Run Tests

make test

This runs all tests with verbose output.

Clean Build Artifacts

make clean

Removes the build/ directory.

Testing

Running Tests

# Run all tests
make test

# Run tests for a specific package
go test ./internal/aptfile/...

# Run tests with coverage
go test -cover ./...

Writing Tests

Place test files alongside source files with _test.go suffix
Use standard Go testing patterns
Mock external commands (apt-get, add-apt-repository) for unit tests
Use integration tests for end-to-end scenarios

Test Requirements

Tests should be idempotent when possible
Avoid requiring root privileges for unit tests
Use temporary directories for file operations
Clean up after tests

Testing GitHub Actions Locally

There are two ways to test the CI workflow locally before pushing:

Option 1: Quick Test with Makefile (Recommended)

The easiest way is to use the ci-build Makefile target, which mimics the exact CI build step:

# Test with default architecture (amd64) and version from VERSION file
make ci-build

# Test with specific architecture
make ci-build ARCH=arm64

# Test with specific architecture and version
make ci-build ARCH=amd64 VERSION=0.1.5

This will:

Build the binary for the specified architecture
Create a .deb package using nfpm (with the same environment variables as CI)
Rename the package to include architecture in filename
Copy it to artifacts/ directory

Note: This only tests the build step. It doesn’t test the full workflow (version calculation, release creation, etc.).

Option 2: Full Workflow Testing with `act`

For testing the complete GitHub Actions workflow, you can use act:

Installation:

# On macOS
brew install act

# On Linux (using the install script)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Or download from releases: https://github.com/nektos/act/releases

Basic Usage:

# List all workflows
act -l

# Run the build job (dry-run, won't actually build)
act -j build --dryrun

# Run the build job for a specific architecture
act -j build --matrix goarch:amd64 --matrix debarch:amd64

# Run with environment variables
act -j build -e VERSION=0.1.0

Limitations:

act runs workflows in Docker containers, so it’s slower than the Makefile approach
Some GitHub Actions features may not work perfectly (secrets, API calls, etc.)
The release job requires GitHub API access which may not work locally

Recommended Workflow:

Quick iteration: Use make ci-build to test build changes rapidly
Full workflow: Use act before pushing to test the complete workflow
Final verification: Push to a test branch and let GitHub Actions run

Debugging CI Test Failures

When tests pass locally but fail in CI:

Run tests in a CI-like environment (Docker, matches ubuntu-latest):
```
make test-docker
```
This often reproduces the failure locally.
Download the test output artifact when CI fails: In the Actions run, open the “Run tests” step. If the log is truncated, go to the “Summary” tab and download the test-output artifact (uploaded on failure).
Use -failfast (already in CI): Tests stop at the first failure, so the failing test name and error appear at the end of the log.

Code Style

Follow standard Go conventions
Use gofmt for formatting (enforced by make fmt)
Follow the guidelines enforced by golangci-lint
Write clear, self-documenting code
Add comments for exported functions and types

Architecture

For a detailed walkthrough of the internal design — including motivation, component diagrams, data flow for each command, and guidance on where to make changes for new features — see the Architecture page.

Pull Request Guidelines

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/yourusername/apt-bundle.git
Create a branch: git checkout -b feature/your-feature
Make your changes
Run tests: make test
Format code: make fmt
Run linter: make lint
Commit your changes
Push to your fork
Open a Pull Request

PR Guidelines

Keep PRs focused on a single feature or fix
Include tests for new functionality
Update documentation as needed
Ensure all tests pass
Follow the existing code style

Commit Messages

Write clear, descriptive commit messages:

Add support for version pinning in Aptfile

- Parse version strings from apt directives
- Pass version to apt-get install
- Add tests for version parsing

Dependencies

External Dependencies

spf13/cobra: CLI framework

Development Dependencies

golangci/golangci-lint: Linter

Managing Dependencies

# Download dependencies
make deps

# Add a new dependency
go get <package>

# Update dependencies
go get -u ./...
go mod tidy

Binary Characteristics

The apt-bundle binary is designed to be:

Self-contained: Statically linked, no external .so or .dll files
Portable: Works on any Linux system with the same architecture
Small: Stripped debug symbols for minimal size
Fast: Minimal overhead over native apt commands

Release Process

Update version in code (if versioning is implemented)
Update CHANGELOG.md
Create a git tag
Build release binaries
Create GitHub release
Upload binaries

Troubleshooting

Build Issues

Ensure Go 1.21+ is installed: go version
Check go.mod is up to date: go mod tidy
Clean and rebuild: make clean && make build

Test Issues

Some tests may require a Debian/Ubuntu system
Integration tests may need root privileges (use sudo)
Check that required system commands are available

Development Environment

Use direnv or similar for environment management
Consider using Docker for isolated testing
Use go run for quick iteration: go run ./cmd/apt-bundle

CI and Workflow Issues

nfpm not found: The Makefile will auto-install nfpm if it’s missing. For act, ensure Docker is running.

Architecture-specific issues: Test each architecture individually:

make ci-build ARCH=amd64
make ci-build ARCH=arm64
make ci-build ARCH=armhf
make ci-build ARCH=i386

Version format: The CI workflow expects versions in MAJOR.MINOR.PATCH format. The Makefile defaults to VERSION.0 if only MAJOR.MINOR is in the VERSION file.

Resources

Go Documentation
Cobra Documentation
Go Testing
Architecture - Internal design, component diagrams, and feature orientation guide
Project Requirements - Internal specification
Technical Specification - Internal specification

Getting Help

Open an issue on GitHub for bugs or feature requests
Check existing issues and discussions
Review the API Reference for code documentation