Skip to content
This repository was archived by the owner on Jul 7, 2025. It is now read-only.

Developer Documentation

Jump to bottom
AJ edited this page Feb 9, 2024 · 15 revisions

Project Philosophies

  • mainline shall always be in a release-ready state.
  • This project shall produce the primary build artifacts using only one command from a fresh clone on a new machine (./toolbox or npm run clean-verify).
  • The only prerequisite dependency of this project shall be Docker.
  • Continuous Integration tests shall be reproducible on a developer's machine.
  • Behavior is defined by tests, not code.

The Release Process

  1. CI Merge a change into mainline, triggering the Continuous Integration workflow.
  2. CI Build and test the project in a Docker container from both a rootful and rootless Docker context, and store the build artifacts found in build/release/ if the run is successful.
  3. CD If the previous Continuous Integration workflow successfully finished, trigger the Continuous Deployment workflow.
  4. CD If the package.json version is equal or less-than the current released version, stop.
  5. CD Sign the previously uploaded build artifacts (do not rebuild).
  6. CD Create a release and add both the build artifacts and signature file.

ci.yml, cd.yml

Tooling

Toolbox

Toolbox is a shell script designed to be the main entry point for this project. In essence, all toolbox does is run commands in a temporary Docker container defined by a Docker Compose file. This is the primary purpose of this project: a proof of concept of a completely containerized toolchain. A unified environment between each developer and automated runner.

There are some quirks though:

Docker volumes

Reading and writing node_modules with Docker is really slow on Windows. To increase performance, these intermediate directories use Docker volumes instead of a host mount at the cost of additional complexity (mainly, permissions when Docker creates these directories on the host and container).

Permissions

Items created by rootful Docker (like file system mounts) will be owned by root on Linux systems. To get around this, toolbox creates these items itself and sets the owner to the current user. This is accomplished by reading the volumes: entry of the docker compose file with yq to create items on the host, and forward instructions to Dockerfile to create and own the matching items in the image. Running Docker in a rootless context also works.

Clone this wiki locally