Skip to content

Development Guide

Jump to bottom
sat edited this page Dec 31, 2025 · 1 revision

Development Guide

This guide covers building, testing, and releasing dot2net for developers and contributors.

Prerequisites

  • Go: Version 1.21 or later (1.23+ recommended)
  • Git: For version control
  • Docker (optional): For containerized builds

Building

Local Build

Build the binary in the project root directory:

go build .

This creates a dot2net executable in the current directory.

Docker Build

For reproducible builds without installing Go locally:

docker run --rm -v $PWD:/v -w /v golang:1.23 go build -buildvcs=false .

Note: The -buildvcs=false flag is required because the Docker container cannot access the .git directory properly.

Cross-Compilation

Go supports cross-compilation via environment variables:

# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o dot2net-linux-amd64 .

# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o dot2net-darwin-arm64 .

# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o dot2net-darwin-amd64 .

Testing

Running All Tests

go test -v ./...

Running Specific Tests

# Test a specific package
go test -v ./pkg/model
go test -v ./internal/test

# Run a specific test function
go test -v ./pkg/model -run TestLoadConfig

Example Scenario Tests

The internal/test/example_test.go file runs tests against all example scenarios in the example/ directory. Each scenario compares generated output against expected files in expected/ subdirectories.

Updating Expected Values

When you intentionally change output behavior, update the expected values:

# Update all scenarios
./tool/generate_expected.sh

# Update a specific scenario
./tool/generate_expected.sh scenario_name

GitHub Actions (CI/CD)

Automated Workflow

The project uses GitHub Actions for automated testing and releases. The workflow is defined in .github/workflows/release.yaml.

Trigger

The workflow runs when a version tag is pushed:

git tag v0.7.0
git push origin v0.7.0

Tag format must match v[0-9]+.[0-9]+.[0-9]+ (e.g., v0.6.2, v1.0.0).

Workflow Steps

  1. Test: Run tests on multiple platforms

    • Linux (ubuntu-latest)
    • macOS ARM (macos-latest)
    • macOS Intel (macos-15-intel)

  2. Build: Cross-compile binaries for:

    • linux-amd64
    • linux-arm64
    • darwin-amd64
    • darwin-arm64

  3. Release: Create a GitHub Release with binaries attached

Viewing Results

Release Process

1. Update Version

Edit main.go and update the Version variable:

var (
    Version = "0.7.0"
)

2. Update CHANGELOG

Add a new section to CHANGELOG.md:

## [0.7.0] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Change description

### Fixed
- Bug fix description

Don't forget to update the comparison links at the bottom of the file.

3. Commit and Push

git add main.go CHANGELOG.md
git commit -m "v0.7.0; description of changes"
git push origin master

4. Create and Push Tag

git tag v0.7.0
git push origin v0.7.0

This triggers the GitHub Actions workflow, which automatically:

  • Runs tests
  • Builds binaries
  • Creates a GitHub Release
  • Uploads binaries to the release

5. Verify Release

Check the Releases page to confirm:

  • Release was created
  • All binaries are attached
  • Release notes are correct

Downloading Release Binaries

Latest Release

# Linux (amd64)
curl -L -o dot2net https://github.com/cpflat/dot2net/releases/latest/download/dot2net-linux-amd64
chmod +x dot2net

# macOS (Apple Silicon)
curl -L -o dot2net https://github.com/cpflat/dot2net/releases/latest/download/dot2net-darwin-arm64
chmod +x dot2net

Specific Version

curl -L -o dot2net https://github.com/cpflat/dot2net/releases/download/v0.6.2/dot2net-linux-amd64

Known Issues

Windows Support

Windows is currently not supported in CI/CD due to CRLF line ending issues in tests. See TODO 16 for details.

If you need Windows builds, you can cross-compile locally:

GOOS=windows GOARCH=amd64 go build -o dot2net.exe .

See Also

Clone this wiki locally