@Snekwranglers

Please organise your knowledge here. All of you should have edit access to all post tagged Documentation.

Documentation

As the state of the tooling is still in flux, the best thing to do to get an idea for how things work is to look at the recipes in the main snekpit recipe repo.

The other thing to do is to look at the macro %actions and %(definitions) in the boulder code repo.

The naming of concepts has been tweaked compared to what some of you might be used to, with the primary purpose being more sensible and clear semantics in terms of natural speech and its supporting mental models.

Additionally, it might be worth pointing out that this is not $otheros!

You are encouraged to forget everything you thought you knew about how things are supposed to work and be open to the different goals of Serpent OS which spawned the tooling you're about to use. The fully fleshed out workflow is also not yet ready for you to use, so things will feel rather manual initially.

How to get started writing a recipe

To get a basic recipe, use boulder new -h to get started.

Thanks to work done by our contributors, git upstreams can now be used in recipes .

Packaging Guidelines

Follow these guidelines and build consensus by talking to your peers if a situation arise that they don't cover. If the BDFL chips in, listen carefully.

Naming

Package names and categories (=dirs) are all-lowercase: lang/python, console/nano

Package splitting

No standalone -devel packages. If a package is all headers, they should be in the %(name) package

The recipe `pkg/` dir and `%(pkgdir)`

Place extra files such as patches, vendor configs etc. in the pkg/ dir inside the recipe dir. Files inside pkg/ will automatically be copied over to %(pkgdir) during boulder builds, from where each can be referenced as %(pkgdir)/path/filename in the recipe. The directory name pkg/ was chosen because it's short and stands out in tree invocations.

What to commit

git add manifest.x86_64.bin manifest.x86_64.jsonc monitoring.yml stone.yml

manifest.x86_64.bin Binary moss readable file used to create moss collection stone.index files for dep resolution etc.
manifest.x86_64.jsonc Human readable version of manifest.bin used for git diff introspection purposes
monitoring.yml See the security monitoring discussion
stone.yml The actual build recipe

Commit messages

The goal here is to make the git shortlog of the monorepos easy to read at a glance.

Use a category/pkg: verb <foo> format with one commit per package change.

Examples:

shells/fish: Add vX.Y
shells/fish: Update to vX.Y
shells/fish: Fix (...)

Bump release for functional recipe changes only; do not bump release for no functional change commits (documentation typos, formatting).

No functional change commits use the [NFC] tag (policy in clang, worth adopting):

shells/fish: [NFC] Tweak comments.

Recipe licensing

We only accept ~~Zlib~~ MPL-2.0 licensed code and recipe contributions due to the desirable nature of its patent protections. boulder new has been updated to use a REUSE compliant license header, but existing recipes will need to be updated with the following REUSE-compliant verbiage at the top:

#
# SPDX-FileCopyrightText: © 2020-2023 Serpent OS Developers
#
# SPDX-License-Identifier: MPL-2.0
#