Skip to content

Latest commit

 

History

History
116 lines (87 loc) · 4.48 KB

DEVELOPMENT.md

File metadata and controls

116 lines (87 loc) · 4.48 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
  • jq and yj utilities
    • macOS: brew install jq yj
    • Windows:
      • choco insall jq -y
      • go get github.com/sclevine/yj
  • Make (and build tools)
    • macOS: xcode-select --install
    • Windows:
      • choco install cygwin make -y
      • [Environment]::SetEnvironmentVariable("PATH", "C:\tools\cygwin\bin;$ENV:PATH", "MACHINE")

Caveats

  • The acceptance tests require the docker daemon to be able to communicate with a local containerized insecure registry. On Docker Desktop 3.3.x, this may result in failures such as: Expected nil: push response: : Get http://localhost:<port>/v2/: dial tcp [::1]:<port>: connect: connection refused. To fix these failures, it may be necessary to add the following to the Docker Desktop Engine config:
    • macOS: Docker > Preferences > Docker Engine:
  "insecure-registries": [
    "<my-host-ip>/32"
  ]
  • Some of the Windows acceptance tests use license restricted base images. By default, the docker deamon will not publish layers from these images when pushing to a registry which can result in test failures with error messages such as: Ignoring image "X" because it was corrupt. To fix these failures you must enable pushing nondistributable artifacts to the test registry by adding the following to your Docker Desktop Engine config:
    • %programdata%\docker\config\daemon.json:
{
  "allow-nondistributable-artifacts": [
    "<my-host-ip>/32"
  ]
}

Testing GitHub actions on forks

The lifecycle release process involves chaining a series of GitHub actions together such that:

  • The "build" workflow creates the artifacts
    • .tgz files containing the lifecycle binaries, shasums for the .tgz files, an SBOM, etc.
    • OCI images containing the lifecycle binaries, tagged with their commit sha (for more information, see RELEASE.md)
  • The "draft-release" workflow finds the artifacts and downloads them, creating the draft release
  • The "post-release" workflow re-tags the OCI images that were created during the "build" workflow with the release version

It can be rather cumbersome to test changes to these workflows, as they are heavily intertwined. Thus we recommend forking the buildpacks/lifecycle repository in GitHub and running through the entire release process end-to-end. For the fork, it is necessary to add the following secrets:

  • DOCKER_PASSWORD (if not using ghcr.io)
  • DOCKER_USERNAME (if not using ghcr.io)

The tools/test-fork.sh script can be used to update the source code to reflect the state of the fork. It can be invoked like so: ./tools/test-fork.sh <registry repo name>

Tasks

To test, build, and package binaries into an archive, simply run:

$ make all

This will create archives at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz and out/lifecycle-<LIFECYCLE_VERSION>+windows.x86-64.tgz.

LIFECYCLE_VERSION defaults to the value returned by git describe --tags if not on a release branch (for more information about the release process, see RELEASE). It can be changed by prepending LIFECYCLE_VERSION=<some version> to the make command. For example:

$ LIFECYCLE_VERSION=1.2.3 make all

Steps can also be run individually as shown below.

Test

Formats, vets, and tests the code.

$ make test

Mocks

We use mock generators like most golang projects to help with our testing. To make new mocks:

$ make generate
$ make format lint

This is because the mock generator will make a larger diff that the formatter will fix.

Build

Builds binaries to out/linux/lifecycle/ and out/windows/lifecycle/.

$ make build

To clean the out/ directory, run make clean.

Package

Creates archives at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz and out/lifecycle-<LIFECYCLE_VERSION>+windows.x86-64.tgz, using the contents of the out/linux/lifecycle/ directory, for the given (or default) LIFECYCLE_VERSION.

$ make package