Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Everybody is invited and welcome to contribute to PiCompose. Documentation fixes
- Check your changes (`bash -n` for shell scripts, `yamllint` for workflows).
- Create a Pull Request against the `main` branch and tick exactly one box under "Types of changes". CI derives the label from it, and the label decides where the PR appears in the release notes.

Pushing a branch to your fork starts the image build workflows if Actions are enabled there, so expect long build times.
Images are not built for branches or pull requests automatically. A maintainer starts the `Build All PiCompose` workflow manually for a branch when an image is needed to test a change. In your fork you can run it yourself from the Actions tab if Actions are enabled there, so expect long build times.

## Feature suggestions

Expand Down
5 changes: 1 addition & 4 deletions .github/workflows/build-all.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,9 @@ on:
push:
branches:
- main
- feature/*
- fix/*
- hotfix/*
- bugfix/*
tags:
- 'v*.*.*'
workflow_dispatch:

jobs:
# NO SPECIFIC HARDWARE
Expand Down
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Behaviour

- NEVER automatically reply on GitHub (PRs, issues or discussions) and NEVER push or open a PR without explicit consent from the developer.
- Pushing a `feature/*`, `fix/*`, `hotfix/*` or `bugfix/*` branch starts a full image build of every variant and publishes a prerelease named after the branch. Only push when the developer asks for it, because the build is expensive. See "Branching and PRs" for the branch names.
- Pushing a branch does not build images. A full image build of every variant, published as a prerelease named after the branch, only starts when the developer runs `Build All PiCompose` manually (`workflow_dispatch`) for that branch, because the build is expensive. See "Branching and PRs".
- Images cannot be built or booted locally. Never claim that image, driver, audio or boot behavior is verified unless it was actually exercised on hardware. State plainly what was only syntax-checked.
- When a change alters what users see or must configure (`picompose.conf` options, `/compose` layout, default services, supported hardware), update `README.md` and the matching file in `docs/` in the same change. Breaking changes also go into `breaking_changes.md`.
- When the code and the docs contradict each other, ask which one is wrong instead of silently picking one.
Expand Down Expand Up @@ -64,9 +64,9 @@ Titles describe the change functionally in the style of the existing history, fo

- All PRs target `main`.
- Release images are built from `v*.*.*` tags.
- Name the branch of a change after its type: `feature/<name>`, `fix/<name>`, `hotfix/<name>` or `bugfix/<name>`. Only these prefixes (and `main` and tags) start the image build of `build-all.yml`, which is how a change to a stage, a driver, a configuration file or any other content of the image is tested before the merge. A change to the image must therefore never use another prefix, for example `my-change` or `picompose-fix`, because then the PR has no build.
- Changes that do not affect the image (documentation, AI instructions, repository settings) use another prefix, for example `docs/<name>` or `ci/<name>`, so that no build of ten images is started for them.
- Do not push a branch with one of the build prefixes before the developer asked for it, and say in the PR that the build runs.
- Name the branch of a change after its type: `feature/<name>`, `fix/<name>`, `hotfix/<name>` or `bugfix/<name>` for changes to the image, `docs/<name>` or `ci/<name>` for documentation, AI instructions and repository settings.
- The image build of `build-all.yml` starts only for pushes to `main`, for `v*.*.*` tags and on request. A change to a stage, a driver, a configuration file or any other content of the image is tested before the merge by running `Build All PiCompose` manually for the branch (Actions tab, "Run workflow", or `gh workflow run build-all.yml --ref <branch>`). The branch name does not matter for this.
- Never start the build yourself. Ask the developer to start it and say in the PR that an image build is still pending.

## Verification Checklist

Expand All @@ -76,7 +76,7 @@ Before claiming completion:
- [ ] Did NOT claim image or hardware behavior is verified unless it was actually run on a Raspberry Pi
- [ ] `README.md`, `docs/` and `breaking_changes.md` match the change
- [ ] Changes are focused on one feature or fix per change
- [ ] The branch name fits the change: a build prefix for changes to the image, another prefix for documentation only
- [ ] The branch name fits the change: `feature/`, `fix/`, `hotfix/` or `bugfix/` for changes to the image, `docs/` or `ci/` for the rest

## Areas Requiring Extra Care

Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Dense map of the repository for AI agents. `AGENTS.md` (imported above) holds th
## Build pipeline

```
push to main / feature/* / fix/* / hotfix/* / bugfix/* or tag v*.*.*
push to main or tag v*.*.* or manual run (workflow_dispatch) on any branch
└─ build-all.yml one job per image variant
└─ build-image-template.yml (workflow_call)
├─ usimd/pi-gen-action on ubuntu-24.04-arm, release trixie, user pi, SSH on
Expand Down Expand Up @@ -103,7 +103,7 @@ The LVA options live in `03-stage-linux-voice-assistant/01-linux-voice-assistant
- The default login is `pi` / `raspberry`, and the Raspberry Pi Imager customization must keep the user `pi` because services and paths assume it.
- A manual reboot after the first boot is required for the audio driver to show up. This is documented behavior, not a bug.
- `scripts/test-compose-manager.sh` has German comments and log text. New code and docs are English.
- Pushing a `feature/*`, `fix/*`, `hotfix/*` or `bugfix/*` branch builds all ten images and publishes prereleases. Do not push without consent. Changes to the image still need such a branch name (and a PR from it), because that build is the test. Documentation-only changes use a `docs/*` or `ci/*` branch, which is not built. See "Branching and PRs" in `AGENTS.md`.
- Pushing a branch or opening a PR does not build images. Only `main`, `v*.*.*` tags and a manual run of `Build All PiCompose` do. A manual run builds all ten images and publishes prereleases named after the branch, so only the developer starts it. Changes to the image are tested that way before the merge. See "Branching and PRs" in `AGENTS.md`.
- `README.md` links the badge to a workflow file named `build-image.yml`, the real file is `build-all.yml`.

## Documentation map
Expand Down