61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
# PR#48: The README tells other developers how to integrate werkrevisor
|
|
|
|
> **WARNING:** This document describes only the change applied in this PR.
|
|
> It may already be outdated once the next PR is merged.
|
|
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.
|
|
|
|
## The Problem
|
|
|
|
The README describes werkrevisor as it runs on mih09: as a Werkator build, with werkdock and a rootfs archive.
|
|
A developer who wants to use werkrevisor elsewhere does not find out what werkrevisor needs from its environment,
|
|
which parts are specific to Werkator, and which forges it supports.
|
|
GitHub, the most likely question, is not supported, and the README does not say so.
|
|
|
|
## Non-Goals
|
|
|
|
- No support for GitHub or another forge than Gitea; the README names what a port needs.
|
|
- No renamed environment variables: the `WERKATOR_*` names stay, any runner can set them.
|
|
- No published image; a user builds it from the `Dockerfile`.
|
|
- No change of the Werkator sections.
|
|
|
|
## The Scenarios
|
|
|
|
### Feature: the README tells other developers how to integrate werkrevisor
|
|
|
|
#### Scenario#48.01: a developer learns what werkrevisor needs from a CI system
|
|
|
|
So that werkrevisor runs in any CI system that can start a container for a pull request.
|
|
|
|
- **Given** a developer with a Gitea or Forgejo instance and a CI system other than Werkator
|
|
- **When** the developer reads the section "Integration" of the README
|
|
- **Then** the README names the trigger, the environment, the secrets, the gate status and the trust rules
|
|
- **and** it shows an example for Gitea Actions
|
|
|
|
##### Verified by
|
|
|
|
- no automated test: a documentation change, see [README.md](../../README.md#integration)
|
|
|
|
#### Scenario#48.02: a developer learns that GitHub is not supported
|
|
|
|
So that nobody spends time on a setup that cannot work.
|
|
|
|
- **Given** a developer with GitHub repositories
|
|
- **When** the developer reads the section "Integration" of the README
|
|
- **Then** the README says that werkrevisor talks only to the Gitea API
|
|
- **and** it names what a port to another forge needs
|
|
|
|
##### Verified by
|
|
|
|
- no automated test: a documentation change, see [README.md](../../README.md#integration)
|
|
|
|
## The Solution
|
|
|
|
- A new README section "Integration", before "Operations", independent of Werkator and of mih09.
|
|
- The introduction of the README names Werkator as one possible runner.
|
|
- The example for Gitea Actions is a sketch: it was not run on a Gitea runner,
|
|
so the README says to try it on past PRs with `tools/dry-run` first and to start with `yellow_gate = "block"`.
|
|
|
|
## Prerequisite PRs
|
|
|
|
- PR#46: werkrevisor 0.22.0, merged.
|