Skip to content

Commit 7c2ca39

Browse files
DaniusKalvDaniusKalv
committed
README: Restructure around workflow catalog
1 parent 95b328b commit 7c2ca39

1 file changed

Lines changed: 35 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 35 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,45 @@
22

33
[![Selftest](https://github.com/Kurokesu/ci/actions/workflows/selftest.yml/badge.svg)](https://github.com/Kurokesu/ci/actions/workflows/selftest.yml)
44

5-
Shared release plumbing for Kurokesu repos: reusable GitHub Actions workflows, canonical release scripts and the archive public keyring.
5+
Shared CI for Kurokesu repos: reusable GitHub Actions workflows, canonical release scripts and archive public keyring. Callers reference workflows here with thin shims at `@main`, so fixes land once and propagate without caller commits.
66

7-
Workflows group by release family. The `dkms-*` pair serves DKMS driver packaging repos. `deb-sign.yml` and `deb-publish.yml` are family-agnostic building blocks for any `.deb` release pipeline. Callers reference the workflows here with thin shims at `@main`.
7+
## Workflows
88

9-
## DKMS workflows
10-
11-
Both assume a DEP-14 layout in the calling repo: driver source on `main`, tagged `v<upstream>` per release, and packaging recipe on `debian/latest`, tagged `debian/<upstream>-<revision>`.
12-
13-
### dkms-build.yml
9+
| Workflow | Purpose | Called from |
10+
| --- | --- | --- |
11+
| `kernel-code-style.yml` | clang-format plus kernel checkpatch, profile per `platform` input | driver repo `main` shim |
12+
| `dkms-build.yml` | DKMS source package plus arch:all `.deb` in a clean container, callers pass nothing repo-specific | packaging branch `ci.yml` shim |
13+
| `dkms-release.yml` | release pipeline on `debian/*` tag push: verify tags, build, sign, publish | packaging branch `release.yml` shim |
14+
| `deb-sign.yml` | bundle artifacts, sign `SHA256SUMS` with archive key, self-verify | `dkms-release.yml` |
15+
| `deb-publish.yml` | GitHub pre-release from `release-assets` artifact, re-run refreshes assets | `dkms-release.yml` |
1416

15-
Builds a DKMS source package plus its arch:all `.deb` in a clean container. Package name comes from the recipe's `debian/changelog` `Source:` field and build dependencies come from `debian/control` via `apt-get build-dep`, so callers pass nothing repo-specific.
17+
`selftest.yml` is this repo's own CI. It runs `dkms-build.yml` against dummy DKMS fixtures on `selftest/*` orphan branches, one plain-version pair and one semver pre-release pair. Sign and publish have no selftest.
1618

17-
Inputs:
19+
## Kernel code style
1820

19-
| Input | Required | Default | Purpose |
20-
| --- | --- | --- | --- |
21-
| `upstream-ref` | yes | | Ref of driver source to build (branch or tag) |
22-
| `source-repo` | no | caller repo | owner/repo of driver source |
23-
| `recipe-repo` | no | caller repo | owner/repo of packaging recipe |
24-
| `recipe-ref` | no | caller SHA | Ref of recipe checkout |
25-
| `container-image` | no | `debian:trixie` | Image the package is built in |
21+
Two jobs: clang-format against caller's `.clang-format` and mainline `checkpatch.pl` with zero findings tolerated. checkpatch enforces Linux kernel coding style, hence the `kernel-` prefix, userspace projects should not call this. `platform` input picks the checkpatch profile. `rpi` runs `--strict`, these drivers hold the mainline bar. `jetson` drops `--strict` and ignores `TRACING_LOGGING`, NVIDIA's tegracam reference is the standard for modules that build against nvidia-oot and cannot go upstream. Full rationale in the workflow header.
2622

27-
Outputs: `package`, `packaging-version` and `artifact` (name of the uploaded artifact carrying the `.deb`, `.dsc`, `.orig.tar.gz`, `.changes`, `.buildinfo` and `.debian.tar.xz`).
23+
Caller shim, `code-style.yml` on `main`:
2824

29-
### dkms-release.yml
25+
```yaml
26+
on:
27+
push:
28+
branches: [main]
29+
pull_request:
30+
branches: [main]
31+
workflow_dispatch:
32+
permissions:
33+
contents: read
34+
jobs:
35+
code-style:
36+
uses: Kurokesu/ci/.github/workflows/kernel-code-style.yml@main
37+
with:
38+
platform: rpi
39+
```
3040
31-
Full release pipeline on a `debian/<full-version>` tag push. Verifies the paired `v<upstream>` source tag exists and the tag matches `debian/changelog`, then builds, signs and publishes a GitHub pre-release with notes seeded from the top changelog entry. Requires the `ARCHIVE_GPG_SIGNING_KEY` secret (org-level, pass with `secrets: inherit`).
41+
## DKMS release family
3242
33-
### Caller shims
43+
`dkms-build.yml` and `dkms-release.yml` assume DEP-14 layout in the calling repo: driver source on `main` tagged `v<upstream>`, packaging recipe on `debian/latest` tagged `debian/<upstream>-<revision>`. Package name and build dependencies come from the recipe. Release verifies paired tags against `debian/changelog`, then builds, signs and publishes a GitHub pre-release. Signing needs the org-level `ARCHIVE_GPG_SIGNING_KEY` secret, passed with `secrets: inherit`.
3444

3545
`release.yml` on the packaging branch:
3646

@@ -65,37 +75,21 @@ jobs:
6575

6676
Shims live on the packaging branch, not `main`, because GitHub Actions resolves `pull_request` and tag-push triggers from a base branch's own workflow files.
6777

68-
## Shared workflows
69-
70-
### deb-sign.yml
71-
72-
Bundles build artifacts into per-artifact tarballs, writes `SHA256SUMS`, signs it with the archive key and verifies the signature against `keys/kurokesu-archive-keyring.gpg` from this repo. Uploads the result as the `release-assets` artifact.
73-
74-
### deb-publish.yml
75-
76-
Creates a pre-release on the caller's repo from the `release-assets` artifact. A re-run refreshes assets and leaves title, notes and the Pre-release flag intact. Inputs: `tag` (release tag, also the title) and `notes` (initial notes for a new release).
77-
78-
## Selftest
79-
80-
`selftest.yml` is this repo's own CI. It calls `dkms-build.yml` against the dummy DKMS fixtures on the `selftest/*` orphan branches, each pair arranged like a caller's `main` and `debian/latest`: a plain version on `selftest/upstream` + `selftest/recipe` and a semver pre-release on the `selftest/*-pre` pair. Both artifact sets are asserted. Sign and publish have no selftest.
81-
82-
## Release scripts
83-
84-
Canonical names in `scripts/` are family-suffixed (`release-<family>.sh`) so sibling families can sit beside each other. Callers carry no copy. The packaging branch root has a thin `release.sh` launcher that resolves the same ref as the workflow shims to a commit SHA, prints it for the audit trail, fetches the canonical script at that SHA and runs it with the caller's arguments. Fetching at the shims' ref keeps maintainer tooling and CI on one protocol version, and script fixes propagate without caller commits.
78+
### Release scripts
8579

86-
`scripts/release-dkms.sh` cuts a paired-tag DKMS release. Operator commands:
80+
Canonical scripts in `scripts/` are family-suffixed (`release-<family>.sh`). Callers carry no copy, only a thin `release.sh` launcher that resolves the shims' ref to a commit SHA, prints it for the audit trail and fetches the canonical script at that SHA. Maintainer tooling and CI stay on one protocol version.
8781

8882
```bash
8983
./release.sh --prepare # open a changelog entry from dkms.conf on main
9084
./release.sh # dry run, validate tags and CI state
9185
./release.sh --execute # tag and push atomically
9286
```
9387

94-
`dkms.conf` on the calling repo's `main` is the one place a human bumps a version. The script derives everything else from `debian/changelog` and refuses on version drift, red CI or retag attempts. `--prepare` attributes the changelog entry from the operator's exported `DEBEMAIL` (`Name <email>`) and refuses to run without it. The opened entry carries an `EDIT ME` placeholder and the dry run and `--execute` refuse to cut tags while it remains, so the release notes always get a written entry.
88+
`dkms.conf` on the calling repo's `main` is the one place a human bumps a version. Script derives everything else from `debian/changelog` and refuses on version drift, red CI, retag attempts or an unedited `EDIT ME` changelog entry.
9589

9690
## Versioning
9791

98-
`dkms.conf` carries the version in semver form. Plain `X.Y.Z` versions pass through every layer unchanged. Semver pre-releases change spelling per layer, because Debian spells pre-release with `~` and git refs cannot carry `~` at all:
92+
`dkms.conf` carries the version in semver form. Plain `X.Y.Z` passes through every layer unchanged. Pre-releases change spelling per layer, because Debian spells pre-release with `~` and git refs cannot carry `~` at all:
9993

10094
| Layer | Form | Example |
10195
| --- | --- | --- |
@@ -105,7 +99,7 @@ Canonical names in `scripts/` are family-suffixed (`release-<family>.sh`) so sib
10599
| Packaging tag | `~` becomes `_` (DEP-14) | `debian/0.2.0_beta.1-1` |
106100
| Release asset tarball | `~` becomes `_` (GitHub forbids `~` in asset names) | `<package>_0.2.0_beta.1-1.tar.gz` |
107101

108-
The pre-release grammar is machine-enforced as `(alpha|beta|rc).N`, the range where dpkg and semver ordering agree. `release-dkms.sh --prepare` checks it before opening a changelog entry and the `dkms-release.yml` preflight checks it on every tag. The apt archive refuses `~` versions into its stable suites at the manifest level.
102+
Pre-release grammar is machine-enforced as `(alpha|beta|rc).N`, the range where dpkg and semver ordering agree. `release.sh --prepare` checks it before opening a changelog entry and the release preflight checks it on every tag. apt archive refuses `~` versions into its stable suites.
109103

110104
## Keys
111105

0 commit comments

Comments
 (0)