Development

Prerequisites

Git
- macOS: (built-in)
- Windows:
  - choco install git -y
  - git config --global core.autocrlf false
Go
- macOS: brew install go
- Windows: choco install golang -y
Docker
Make (and build tools)
- macOS: xcode-select --install
- Windows:
  - choco install cygwin make -y
  - [Environment]::SetEnvironmentVariable("PATH", "C:\tools\cygwin\bin;$ENV:PATH", "MACHINE")

Alternatively, you can use Gitpod to run pre-configured dev environment in the cloud right from your browser

Windows Caveats

Symlinks - Some of our tests attempt to create symlinks. On Windows, this requires the permission to be provided.

Testing GitHub actions on forks

The pack release process involves chaining a series of GitHub actions together, such as:

The "build" workflow, which creates:
- .tgz files containing the pack binaries and shasums for the .tgz files
- a draft release with the above artifacts
The "delivery-docker" workflow, which builds and pushes OCI images containing the pack binary
The "benchmark" workflow, which runs performance checks for each commit and uploads reports to GitHub Pages

It can be rather cumbersome to test changes to these workflows, as they are heavily intertwined. Thus, we recommend forking the buildpacks/pack repository on GitHub and running through the entire release process end-to-end.

For the fork, it is necessary to complete the following preparations:

Add the following secrets:
- DOCKER_PASSWORD for the delivery-docker workflow, if not using ghcr.io
- DOCKER_USERNAME for the delivery-docker workflow, if not using ghcr.io
- DEPLOY_KEY for the release-merge workflow, as a SSH private key for repository access
Enable the issues feature on the repository and create status/triage and type/bug labels for the check-latest-release workflow
Create a branch named gh-pages for uploading benchmark reports for the benchmark workflow

The tools/test-fork.sh script can be used to update the source code to reflect the state of the fork and disable workflows that should not run on the fork repository. It can be invoked like so: ./tools/test-fork.sh <registry repo name>

Tasks

Building

To build pack:

make build

This will output the binary to the directory out/.

Options:

ENV_VAR	Description	Default
GOCMD	Change the `go` executable. For example, richgo for testing.	go
PACK_BIN	Change the name or location of the binary relative to `out/`.	pack
PACK_VERSION	Tell `pack` what version to consider itself	`dev`

NOTE: This project uses go modules for dependency management.

Testing

To run unit and integration tests:

shell

make unit

Test output will be streamed to your terminal and also saved to the file out/unit

To run acceptance tests:

shell

make acceptance

Test output will be streamed to your terminal and also saved to the file out/acceptance

Alternately, to run all tests:

shell

make test

To run our full acceptance suite (including cross-compatibility for n-1 pack and lifecycle):

shell

make acceptance-all

Tidy

To format the code:

shell

make format

To tidy up the codebase and dependencies:

shell

make tidy

Verification

To verify formatting and code quality:

shell

make verify

Prepare for PR

Runs various checks to ensure compliance:

shell

make prepare-for-pr

Acceptance Tests

Some options users can provide to our acceptance tests are:

ENV_VAR	Description	Default
ACCEPTANCE_SUITE_CONFIG	A set of configurations for how to run the acceptance tests, describing the version of `pack` used for testing, the version of `pack` used to create the builders used in the test, and the version of `lifecycle` binaries used to test with Github	`[{"pack": "current", "pack_create_builder": "current", "lifecycle": "default"}]'`
COMPILE_PACK_WITH_VERSION	Tell `pack` what version to consider itself	`dev`
GITHUB_TOKEN	A Github Token, used when downloading `pack` and `lifecycle` releases from Github during the test setup	""
LIFECYCLE_IMAGE	Image reference to be used in untrusted builder workflows	docker.io/buildpacksio/lifecycle:<lifecycle version>
LIFECYCLE_PATH	Path to a `.tgz` file filled with a set of `lifecycle` binaries	The Github release for the default version of lifecycle in `pack`
PACK_PATH	Path to a `pack` executable.	A compiled version of the current branch
PREVIOUS_LIFECYCLE_IMAGE	Image reference to be used in untrusted builder workflows, used to test compatibility of `pack` with the n-1 version of the `lifecycle`	docker.io/buildpacksio/lifecycle:<PREVIOUS_LIFECYCLE_PATH lifecycle version>, buildpacksio/lifecycle:<n-1 lifecycle version>
PREVIOUS_LIFECYCLE_PATH	Path to a `.tgz` file filled with a set of `lifecycle` binaries, used to test compatibility of `pack` with the n-1 version of the `lifecycle`	The Github release for n-1 release of `lifecycle`
PREVIOUS_PACK_FIXTURES_PATH	Path to a set of fixtures, used to override the most up-to-date fixtures, in case of changed functionality	`acceptance/testdata/pack_previous_fixtures_overrides`
PREVIOUS_PACK_PATH	Path to a `pack` executable, used to test compatibility with n-1 version of `pack`	The most recent release from `pack`'s Github release