105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# PR#63: each repository chooses and tunes its risk categories in .werkrevisor.toml
|
|
|
|
> **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
|
|
|
|
Which risks matter depends on the ecosystem of a repository, and since PR#46 werkrevisor keeps them in templates.
|
|
Only the host config selects a template, and no repository can change one category.
|
|
werkcrappit, a Gradle and PIT plugin without Spring, fits `jvm-spring-backend` only in part,
|
|
and werkator, a build system, has its own risks, e.g. in the slots of parallel builds.
|
|
The plan of 2026-10-08 moves the categories into the `.werkrevisor.toml` of each repository.
|
|
|
|
## Non-Goals
|
|
|
|
- No change of the templates; they stay the starting point.
|
|
- No change of the rule that every change of `.werkrevisor.toml` needs a human and counts only from the default branch.
|
|
|
|
## The Scenarios
|
|
|
|
### Feature: each repository chooses and tunes its risk categories
|
|
|
|
#### Background
|
|
|
|
- **Given** the host config judges every file with Jev and allows the repository to tune the risks
|
|
|
|
#### Scenario#63.01: the repository chooses the template
|
|
|
|
So that a repository names its ecosystem itself.
|
|
|
|
- **Given** the `.werkrevisor.toml` of the repository sets `[path_judge] risk_template = "jvm-spring-backend"`
|
|
- **When** werkrevisor reviews a PR of this repository
|
|
- **Then** Jev answers the categories of this template
|
|
|
|
##### Verified by
|
|
|
|
- [test_risk_repo: test_the_repository_chooses_the_template](../../tests/test_risk_repo.py)
|
|
|
|
#### Scenario#63.02: the repository changes the threshold or the consequence of a category
|
|
|
|
So that a category that is noise in this repository gives only a hint.
|
|
|
|
- **Given** the repository sets `action = "hint"` for the category `concurrency`
|
|
- **When** Jev rates a changed file at or above its threshold for this category
|
|
- **Then** the category gives only a hint
|
|
|
|
##### Verified by
|
|
|
|
- [test_risk_repo: test_the_repository_changes_the_threshold_or_the_consequence_of_a_category](../../tests/test_risk_repo.py)
|
|
|
|
#### Scenario#63.03: the repository switches a category off
|
|
|
|
So that a category without meaning in this repository costs no question and no hint.
|
|
|
|
- **Given** the repository sets `action = "off"` for the category `sql_injection`
|
|
- **When** werkrevisor asks Jev about a changed file
|
|
- **Then** Jev gets no question for this category
|
|
|
|
##### Verified by
|
|
|
|
- [test_risk_repo: test_the_repository_switches_a_category_off](../../tests/test_risk_repo.py)
|
|
|
|
#### Scenario#63.04: the repository adds an own category
|
|
|
|
So that a repository names a risk that no template knows, e.g. the slots of parallel builds.
|
|
|
|
- **Given** the repository defines a category with name, title, question, threshold and action
|
|
- **When** Jev rates a changed file at or above its threshold
|
|
- **Then** the review is YELLOW with this category
|
|
|
|
##### Verified by
|
|
|
|
- [test_risk_repo: test_the_repository_adds_an_own_category](../../tests/test_risk_repo.py)
|
|
|
|
#### Scenario#63.05: the host can forbid the tuning
|
|
|
|
So that a host such as hs.hsadmin.ng keeps its categories fixed.
|
|
|
|
- **Given** the host config sets `[path_judge] repository_may_tune_risks = false`
|
|
- **When** the `.werkrevisor.toml` of the repository sets a risk template or a category
|
|
- **Then** the config is refused with a message that the host does not allow it
|
|
|
|
##### Verified by
|
|
|
|
- [test_risk_repo: test_the_host_can_forbid_the_tuning](../../tests/test_risk_repo.py)
|
|
|
|
## The Solution
|
|
|
|
- `.werkrevisor.toml` may set `[path_judge] risk_template` and a list `[[risk.categories]]`.
|
|
- An entry with the name of a template category changes its `yellow_min`, `orange_min` or `action`; `action = "off"` removes it.
|
|
- An entry with a new name is a category of its own and needs name, title, question, `yellow_min` and `action`;
|
|
`kinds` defaults to main code, and `orange_min` is optional, as in a template.
|
|
- The host key `[path_judge] repository_may_tune_risks`, default true, allows both.
|
|
- `risk_template` is no longer host only: tests/test_pathjudge.py drops it from the host-only keys
|
|
and adds `repository_may_tune_risks`.
|
|
- config/hsadmin-ng.toml sets `repository_may_tune_risks = false`, as it already forbids the repository to enable the judge.
|
|
- The inside diagram names the risk template among the keys of `.werkrevisor.toml`.
|
|
- The README describes it with an example; docs/werkrevisor.werkbaum marks the node as merged.
|
|
- werkrevisor 0.30.0.
|
|
|
|
## Prerequisite PRs
|
|
|
|
- PR#62: werkrevisor 0.29.0, merged.
|