Skip to content

Latest commit

 

History

History
85 lines (50 loc) · 4.94 KB

CONTRIBUTING.md

File metadata and controls

85 lines (50 loc) · 4.94 KB
Raw

Contributing to wolfi-dev/os

Setup development environment

To ease the development of Wolfi OS, you can use the Wolfi sdk image that already includes both apko and melange. On Linux and Mac it is also possible to install both the above tools directly into your system.

If you choose not to install the tooling onto your local machine, you can start a container based development environment using

make dev-container

What it does is start the ghcr.io/wolfi-dev/sdk image and mount the current working directory into it.

Write your first Wolfi package

Wolfi packages are built using melange. If you want to learn how packages are built, you can see all the details in the ci-build workflow and in the Makefile.

Start by cloning this repository and create a build configuration YAML file named <your-new-package-name>.yaml in its root directory. If you have any patch files that are needed to build this package, create a folder at the root of the repository with the same name as the package and put the patches there.

Once you're done writing the new package configuration file, you can test it by building the new package.

Building a package

To build an individual package, you can use a make command like this:

make package/<your-new-package-name>

For example, if your package name is "foo", run make package/foo.

This will build the package by invoking melange in a particular way. This invocation is defined in the Makefile, if you're interested to see how this is wired up. Also, you can run Melange directly without using make if you understand what you're doing.

Note: The buildsystem has a cache of source files that may help reduce the time your build takes. Feel free to see if this cache helps you by adding USE_CACHE=yes to the command above. If you encounter issues with this approach, the best advice is to remove the USE_CACHE=no from your command and carry on with your builds.

When the build finishes, your package(s) should be found in the generated ./packages directory.

Scanning your package for vulnerabilities

While you're here, you can scan the package you just built for vulnerabilities, using wolfictl's scan command:

wolfictl scan ./packages/some-architecture/your-package-name-and-version.apk

Check for anything unexpected, or for any CVEs you can patch.

Package versioning

  • When bumping version of a package, you will need to update the version, epoch & shasum (sha256 or sha512) in package YAML file. The version and epoch also need to be bumped in Makefile.

  • epoch needs to be bump when package version remains the same but something else changes. epoch needs to be reset to 0 when it's a new version of the package.

  • melange CLI has a command bump to make it easier. More details are available here.

Some tips

  • melange has a few built-in pipelines. You can see their source code in the melange repository.

  • You don't need to add environment.contents.repositories and environment.contents.keyring. Those are added automatically in the ci-build.yaml script during CI.

  • For patching CVEs, you can follow the documentation here.

  • If you don't want to build all the packages locally, you can install gsutil and use it to sync the prebuilt packages from gs://wolfi-production-registry-destination/os/ bucket:

gsutil -m rsync -r gs://wolfi-production-registry-destination/os/ ./packages

  • If you dont want to install gsutil locally, you can use this image gcr.io/google.com/cloudsdktool/google-cloud-cli:slim which is the official SDK image from GCP and already include gsutil in there.

  • When deciding how to add update: configuration see the update docs

  • When you're ready to submit a PR for a new package or to update a package, make sure your YAML file(s) are formatted correctly, so that they'll pass CI. We use yam for YAML formatting. You should be able to run the yam command from the root of this repo to get all files formatted correctly.

  • When running a lot of melange builds using docker as a runner (default on Mac) you may want to increase the Docker VM CPU, Memory and especially storage resources, else Docker can easily run out of disk space.