CONTRIBUTING

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

Development

To local develop on the image you need to first build the Dockerfile with make build-base. Here you can already verify if the Install is succeeding. Currently we are supporting the two architectures arm64 and amd64

If you want to develop on the functionality of the run-build-functions.sh. Run the make run-local which will leverage the already built image and run it.

Note: For Debugging purpose you can change the make run-local to run the docker image with -e NETLIFY_VERBOSE=1 which will set verbose logging to on.

Running the build

If you are inside the image you need to run the build script:

/opt/build-bin/build

Running functions individually

Additionally you can directly source the build-functions and invoke functions individually:

source /opt/build-bin/run-build-functions.sh

After that the functions like install_dependencies can be run

# Node = 16
# Ruby = 2.6.2
# Yarn = 1.13.0
# Go = 1.16.4
# Python = 3.8
install_dependencies 16 2.6.2 1.13.0 1.16.4 3.8

Linting

ShellCheck usage is recommended, however it is not enforced.

Tests

For testing the Docker Image we use Googles Container Structure Tests. Those tests are used to test the metadata, filesystem or installed binaries of the image.

Installing Container Structure Tests

To install the container tests we recommend doing so by using a package manger like brew:

brew install container-structure-test

Running Container Structure Tests

To run the container structure tests you need to run the following command.

make container-test

For further install instructions please visit the official installation guide.

Testing dynamic Versions

To test Golang or Node.js versions, which are dynamically downloaded via a script on startup we have a set of automated tests in ./tests. These are bats tests that we use to make assertions not only on the correct functioning of our bash/shell scripts, but also of the software provided by our Docker image. For an overview on how bats works see here.

To run those tests you can run the following command which will load the tests in the image and executes them.

make test-local

In General any fix or feature should be accompanied by a set of tests to validate that those changes work as expected.

Developing

We provide a Makefile with a set of utility targets to help with development.

Some examples:

• make test build the test docker image and run the tests in TAP fromat.
• make test-local creates a volume of the tests directory and the build scripts and run the tests inside the container. Useful when developing locally.
• make test-local FILTER=<regex> provide a filter regex string to your test execution in order to select a specific set of tests.
• make run build the base image and run a bash shell in a container based in it in interactive mode.
• make run-local volume the build scripts and run a bash shell in a container based in the build image.

Our changelog is powered by an automated release-please action, which relies on commits following the conventional commit format. For the CI validation to succeed, make sure that your PRs and commits follow the conventional commits format.

CI

The bulk of our CI work takes place in Circle CI.

If you're part of the Netlify org and have write access to the repo, our pipeline will take care of:

• Linting the Dockerfile
• Build your Dockerfile, tag it, and push it to our docker hub repo
• Run the automated bats tests

If you don't have write access to the repo and are submitting a PR via a forked repo, the CI pipeline will still execute for you. The main difference is that it won't push your built image to our docker repo. If required, someone with write accesss to the repo can trigger the push for you. If you require it (mainly useful for testing purposes) reach out to someone on the team :+1:

Releasing

1. Create a PR branching off of focal with your changes applied.
2. Once the PR is approved, merge it into the respective base branch. The merge commit should also follow the conventional commit format.
3. Commits which are prefaced with fix: or feat: will trigger package release PRs created by release-please. Merge these PRs. If you need to manually trigger a release-please PR you can bump the version by creating an empty PR.
4. Wait for the CI pipelines to finish. Renovate should automatically create a PR in buildbot with the latest build-image releases (this may not happen straight away, but you can speed it up by checking the box in the dependency dashboard or manually create a PR to bump the version).
5. Review, test and deploy the PR in buildbot.

Running Test buildbot Releases

If you want to test a particular build-image change before going through the regular release process, you can do so by creating a PR following the process above :point_up: and pointing to any build-image you want. Any branch creates a valid build-image tag in the docker registry. Once the PR in buildbot is created, you can test your build-image change by referring to buildbot's test instructions.

License

By contributing to Netlify's build-image, you agree that your contributions will be licensed under its MIT license.