Developer's Guide

Getting the code

Cloning this repository and change directory to it:

$ go get -d github.com/cnabio/duffle/...
$ cd $(go env GOPATH)/src/github.com/cnabio/duffle

Prerequisites

You need:

• make
• Docker

Containerized Development Environment

To ensure a consistent development environment for all contributors, Duffle relies heavily on Docker containers as sandboxes for all development activities including dependency resolution and executing tests.

make targets seamlessly handle the container orchestration.

If, for whatever reason, you must opt-out of executing development tasks within containers, set the SKIP_DOCKER environment variable to true, but be aware that by doing so, the success or failure of development-related tasks, tests, etc. will be dependent on the state of your system, with no guarantee of the same results in CI.

Developing on Windows

All development-related tasks should "just work" on Linux and Mac OS systems. When developing on Windows, the maintainers strongly recommend utilizing the Windows Subsystem for Linux.

This blog post provides excellent guidance on making the Windows Subsystem for Linux work seamlessly with Docker Desktop (Docker for Windows).

Building

To build everything (binaries for Linux, Mac, and Windows on amd64 architecture) as well as a linux/amd64 Docker image containing the corresponding binary:

$ make build

To build binaries for Linux, Mac, and Windows, but no Docker image:

$ make build-all-bins

To build for one specific OS / architecture:

$ GOOS=<desired OS> GOARCH=<desired architecture> make build-bin

For convenience, you can build for the OS of your choice with amd64 architecture using targets of the form build-<OS>. For example:

$ make build-darwin

To build only the Docker image and nothing else:

$ make build-image

Testing

To run the tests, issue:

$ make test

Linting

To lint the code, issue:

$ make lint

If this detects that some imports need re-organising (errors like "File is not goimports-ed"), issue:

$ make goimports

Dependency Resolution

If, at any time, you need to (re-)resolve the project's dependencies, perhaps because a new one is needed or an existing one is no longer needed, issue:

$ make dep

Debugging

For instructions on using VS Code to debug the Duffle binary, see the debugging document.

Creating a Release

To create a release, simply push a tag and CI will do the rest. The tag should be of the form:

<major>.<minor>.<patch>[-<pre-release>]

Tags conform to Semantic Versioning in syntax and semantics, but must not start with v.

Examples tags are: 0.3.0-beta.3 and 1.0.0.