Skip to content

Latest commit

 

History

History
141 lines (106 loc) · 7.09 KB

DEVELOPMENT.md

File metadata and controls

141 lines (106 loc) · 7.09 KB
Raw

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

Open in Gitpod

Windows Caveats

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:

make unit

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

To run acceptance tests:

make acceptance

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

Alternately, to run all tests:

make test

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

make acceptance-all

Tidy

To format the code:

make format

To tidy up the codebase and dependencies:

make tidy

Verification

To verify formatting and code quality:

make verify

Prepare for PR

Runs various checks to ensure compliance:

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_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:
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