RFD 001: Release Management

[DivineGod]

RFD 001: Release Engineering Process for Dogebox OS

Authors: @DivineGod
Reviewers: @Dogebox-WG/dev
Status: Released
Created: 2025-10-21
Discussion: [link to GitHub Discussion/PR or Issue]

---

Summary

This RFD proposes the release engineering process for Dogebox OS, covering the roles, automation, work-flows, and tooling involved in preparing and publishing a release across the Dogebox ecosystem. This process standardises how we move from merged code to tagged releases with build artefacts available for end users, leveraging much-os-release and GitHub Actions, and backed by a build cache hosted on Collie.

---

Motivation

As Dogebox OS matures, we need a reliable, repeatable, and minimal-intervention release process that:

• Enforces semantic versioning and traceable commit history
• Automates generation of release notes and changelogs
• Builds and publishes reproducible artefacts
• Keeps our build cache hydrated to speed up downstream consumers

This RFD documents the agreed-upon process to ensure clarity among contributors and reliability in our release infrastructure.

---

Background

Dogebox OS is developed across four main repositories within the Dogebox-WG GitHub organisation:

• dpanel
• dkm
• dogeboxd
• os

All commits and PRs across these repositories are required to follow the Conventional Commits specification. This enables automated semantic versioning and changelog generation via tooling.

To facilitate releases, we have developed much-os-release, a CLI tool designed to assist the release engineer in orchestrating tagged releases and release notes.

---

Proposed Process

1. Code Contributions

• Developers submit pull requests to any of the four core repositories.
• All commits must adhere to the Conventional Commits format.
• PR titles must also follow the conventional format to reflect the semantic impact of the change (e.g. feat:, fix:, chore:, etc.).
• Upon merge to the default branch (main), changes are now eligible for inclusion in a release.

2. Preparing a Release

When a release is ready to be cut, a designated release engineer performs the following:

Pre-requisites:

• All four repositories must be cloned locally.
• The local branches must be up to date with main.

Steps:

1. Run much-os-release from the os repository

2. The tool:

   • Parses the commit history using Conventional Commits
   • Determines the appropriate next SemVer version as a whole
   • Generates a unified changelog
   • Tags the repositories with the computed version
   • Pushes tags for each repository
   • Publishes a GitHub release with generated notes

Note: much-os-release only creates a GitHub release for the os repository, though it analyses commit metadata across all four.

3. GitHub Actions on Tag Creation

Once a tag is created in the os repo, two GitHub Actions workflows are triggered:

A. OS Image Build & Upload

• Builds the NixOS images defined in the flake.nix configuration
• Uploads the resulting artefacts to the GitHub release

B. Cache Hydration via Collie Runners

• Dispatches scripts to self-hosted runners on Collie

• These runners:

  • Perform a full NixOS rebuild
  • Populate the Dogebox binary cache with newly built derivations

---

Alternatives Considered

• Manual Releases: Historically considered but rejected due to tedium and risk of inconsistency.

---

Appendix

Conventional Commit Examples

• feat(dpanel): add new auth settings modal
• fix(dogeboxd): correct null dereference on startup
• chore(os): update flake inputs for dkm 0.2.1