Skip to content

Commit 9d4e4a6

Browse files
josecelanojosecelano
committed
Merge torrust#1745: docs(ci): add change-aware workflow issue specs
c027708 docs(ci): add change-aware workflow issue specs (Jose Celano) Pull request description: ## Summary - add the EPIC issue spec for torrust#1742 - add the docs-only CI fast path issue spec for torrust#1743 - add the persistence workflow scoping issue spec for torrust#1744 - rename the reviewed specs out of `docs/issues/drafts/` into final numbered paths ## Validation - `linter markdown` ## Related - torrust#1742 - torrust#1743 - torrust#1744 ACKs for top commit: josecelano: ACK c027708 Tree-SHA512: 45b2906f6aa4c11ed8cb32edb7f58c4c34a6fd426e8b5a908eca104a47bb9105ec8171b883bda8969c162ca0d888a118841d3d2e48f9067b79a28d71b7815344
2 parents 4b47206 + c027708 commit 9d4e4a6

3 files changed

Lines changed: 373 additions & 0 deletions

File tree

‎docs/issues/1742-ci-change-aware-workflows-epic.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# EPIC: Make CI Change-Aware
2+
3+
## Goal
4+
5+
Reduce unnecessary CI time and runner usage by making heavyweight workflows run only when the
6+
changed files can affect the behavior they validate.
7+
8+
The current CI setup runs several expensive workflows for almost every pull request, including
9+
documentation-only changes. That slows down review and merge for low-risk changes and consumes
10+
GitHub-hosted runner minutes without increasing confidence.
11+
12+
This EPIC groups two implementation subissues plus one related research track:
13+
14+
1. Existing issue [#1726](https://github.com/torrust/torrust-tracker/issues/1726), which researches
15+
whether `sccache` can reduce Rust build times for the workflows that still need to run.
16+
2. A new docs-only CI fast path so documentation changes do not wait for full test and E2E
17+
matrices.
18+
3. A new persistence-scoped CI strategy so database compatibility and benchmarking workflows only
19+
run for persistence-relevant changes.
20+
21+
The intent is to reduce waste without weakening the safety net for code changes.
22+
23+
## Why This Is Needed
24+
25+
The following workflows currently run broadly on `push` and `pull_request` events:
26+
27+
- [`.github/workflows/testing.yaml`](../../../.github/workflows/testing.yaml)
28+
- [`.github/workflows/os-compatibility.yaml`](../../../.github/workflows/os-compatibility.yaml)
29+
- [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
30+
- [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)
31+
32+
This has two visible effects:
33+
34+
- Small documentation-only pull requests wait behind workflows that cannot be affected by the
35+
change.
36+
- Persistence-specific workflows run even when a pull request does not touch persistence-related
37+
code.
38+
39+
The repository already has adjacent CI optimization work in progress:
40+
41+
- [#1726](https://github.com/torrust/torrust-tracker/issues/1726) is an evidence-driven research
42+
issue about Rust compilation costs and whether `sccache` should be adopted at all.
43+
- [#1740](../1740-fix-container-workflow-caching.md) addresses container build cache behavior.
44+
45+
That makes this a good time to define a coherent, change-aware CI strategy rather than continuing
46+
with one-off workflow tweaks.
47+
48+
## Scope
49+
50+
This EPIC covers workflow triggering and workflow gating only.
51+
52+
In scope:
53+
54+
- Add a docs-only CI fast path with lightweight checks.
55+
- Restrict persistence-specific workflows to persistence-relevant changes.
56+
- Review required-check behavior so selective triggers do not leave pull requests blocked by
57+
missing or permanently pending checks.
58+
- Document the path rules and rationale in the workflow files.
59+
60+
Out of scope:
61+
62+
- Rewriting the test matrix.
63+
- Replacing the current cache strategy wholesale.
64+
- Container cache optimization already tracked in [#1740](../1740-fix-container-workflow-caching.md).
65+
66+
## Related Research Track
67+
68+
### Research `sccache` impact on remaining heavy workflows
69+
70+
- Existing issue: [#1726](https://github.com/torrust/torrust-tracker/issues/1726)
71+
- Local spec: [docs/issues/1726-reduce-build-times-sccache/ISSUE.md](./1726-reduce-build-times-sccache/ISSUE.md)
72+
- Focus: determine, with benchmarks, whether `sccache` reduces compilation cost for workflows that
73+
still need to run.
74+
- Relationship to this EPIC: complementary, but not a blocker. The docs-only fast path and
75+
persistence scoping issues can proceed independently of the `1726` research outcome.
76+
77+
## Implementation Subissues
78+
79+
### Subissue 1: Add a Docs-Only CI Fast Path
80+
81+
- Issue: [#1743](https://github.com/torrust/torrust-tracker/issues/1743)
82+
- Local spec: [docs/issues/1743-docs-only-ci-fast-path.md](./1743-docs-only-ci-fast-path.md)
83+
- Focus: skip heavyweight workflows for documentation-only changes while still running markdown
84+
and spelling checks.
85+
86+
### Subissue 2: Scope Persistence Workflows by Path
87+
88+
- Issue: [#1744](https://github.com/torrust/torrust-tracker/issues/1744)
89+
- Local spec:
90+
[docs/issues/1744-scope-persistence-workflows-by-path.md](./1744-scope-persistence-workflows-by-path.md)
91+
- Focus: run database compatibility and persistence benchmarking only when changes can affect
92+
persistence behavior.
93+
94+
## Risks and Constraints
95+
96+
### 1. Required checks must remain mergeable
97+
98+
If a workflow is skipped entirely via `paths` or `paths-ignore`, branch protection can treat a
99+
required check as missing. The implementation must either:
100+
101+
- update required-check configuration to match the new workflow model, or
102+
- keep the workflow running and use an early change-detection job that exits green when the
103+
workflow is not relevant.
104+
105+
### 2. `#1726` should not block change-aware trigger work
106+
107+
Issue `#1726` is about reducing the cost of relevant workflows after they start. This EPIC is
108+
about avoiding irrelevant workflow runs in the first place.
109+
110+
That means:
111+
112+
- docs-only fast-path work should not wait for `sccache` research to finish,
113+
- persistence workflow scoping should not wait for `sccache` research to finish, and
114+
- any implementation here should avoid assuming that `sccache` will be adopted.
115+
116+
### 3. "Docs-only" must be defined explicitly
117+
118+
Documentation is not limited to `docs/` in this repository. Relevant documentation paths also
119+
include files such as:
120+
121+
- `README.md`
122+
- `SECURITY.md`
123+
- `AGENTS.md`
124+
- `.github/skills/**/SKILL.md`
125+
- package and console `README.md` files
126+
127+
The subissue should define the exact path set and justify it.
128+
129+
### 4. Docs workflow must stay lightweight even if `#1726` is unresolved
130+
131+
The live `#1726` issue confirms that Rust compilation is a major part of CI cost and that the
132+
benefit of `sccache` is still under research. A docs-only workflow should therefore avoid relying
133+
on Rust compilation for its main checks when possible.
134+
135+
In practice, that means keeping the docs-only workflow lightweight and avoiding unnecessary
136+
workspace compilation. Using the internal `linter` binary is acceptable if its installation and
137+
execution cost stays low enough that the workflow remains fast for documentation-only pull
138+
requests.
139+
140+
### 5. Persistence workflow scope is intentionally narrower than general regression coverage
141+
142+
The persistence-specific workflows are intended to validate schema, migration, query, and
143+
persistence-driver behavior in `tracker-core`, not to provide full cross-package regression
144+
coverage.
145+
146+
For that reason, the corresponding subissue intentionally prefers a narrow trigger centered on
147+
`packages/tracker-core/**` plus workflow-file changes when relevant. Broader compile and
148+
integration regressions remain the responsibility of the general testing workflows.
149+
150+
## Acceptance Criteria
151+
152+
- [ ] A documented change-aware CI strategy exists for docs-only and persistence-related changes.
153+
- [ ] The EPIC links `#1726` as a related research track and links the two new implementation
154+
subissues.
155+
- [ ] The final implementation keeps pull requests mergeable under the repository's required-check
156+
policy.
157+
- [ ] Heavy workflows no longer run for documentation-only pull requests.
158+
- [ ] Persistence-specific workflows no longer run for unrelated changes.
159+
160+
## References
161+
162+
- Related issue: [#1726](https://github.com/torrust/torrust-tracker/issues/1726)
163+
- Related local spec: [docs/issues/1740-fix-container-workflow-caching.md](./1740-fix-container-workflow-caching.md)
164+
- Related workflows:
165+
- [`.github/workflows/testing.yaml`](../../../.github/workflows/testing.yaml)
166+
- [`.github/workflows/os-compatibility.yaml`](../../../.github/workflows/os-compatibility.yaml)
167+
- [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
168+
- [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)

‎docs/issues/1743-docs-only-ci-fast-path.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Add a Docs-Only CI Fast Path
2+
3+
## Goal
4+
5+
Avoid running heavyweight test, compatibility, and E2E workflows for documentation-only pull
6+
requests while still validating documentation quality in CI.
7+
8+
## Problem
9+
10+
Documentation changes currently trigger the same expensive workflows as code changes, including
11+
the `Testing` workflow in [`.github/workflows/testing.yaml`](../../../.github/workflows/testing.yaml).
12+
That workflow runs full-workspace linters, tests, and Docker-based E2E jobs, which is slow and
13+
unnecessary when a pull request only changes documentation.
14+
15+
This is particularly costly in this repository because AI-assisted work produces frequent updates
16+
to issue specs, ADRs, agent instructions, and other Markdown documents.
17+
18+
## Constraints
19+
20+
### 1. Documentation still needs CI coverage
21+
22+
We should not skip CI entirely for docs-only changes. At minimum, documentation-only pull requests
23+
should run:
24+
25+
- Markdown linting
26+
- Spell checking (`cspell`)
27+
28+
These checks should stay lightweight. Because [#1726](https://github.com/torrust/torrust-tracker/issues/1726)
29+
is still researching whether Rust compilation can be sped up enough in CI, this issue should avoid
30+
designs that introduce unnecessary workspace compilation just to validate documentation.
31+
32+
### 2. "Docs-only" must cover all documentation surfaces
33+
34+
This repository stores documentation in multiple places, not only in `docs/`. The trigger rules
35+
should review at least the following categories:
36+
37+
- `docs/**`
38+
- top-level Markdown such as `README.md`, `SECURITY.md`, and `AGENTS.md`
39+
- package `README.md` files
40+
- console `README.md` files
41+
- `.github/skills/**/SKILL.md`
42+
- `.github/agents/*.md`
43+
44+
The issue implementation should define the final path set explicitly.
45+
46+
### 3. Required checks must not block merge
47+
48+
If the repository marks heavyweight workflows as required checks, skipping them entirely with
49+
`paths-ignore` may leave pull requests stuck. For this issue, the preferred approach is to update
50+
branch protection so heavyweight workflows are no longer required for documentation-only pull
51+
requests.
52+
53+
Keeping workflows running only to satisfy required-check mechanics defeats much of the value of a
54+
docs-only fast path. Since pull requests are reviewed manually before merge, this issue should
55+
prioritize faster workflow execution over preserving the current required-check set unchanged.
56+
57+
## Proposed Changes
58+
59+
### Task 1: Define the docs-only path policy
60+
61+
- [ ] List every documentation path category that should count as "docs-only".
62+
- [ ] List the non-doc paths that should always force full CI, even if Markdown files also
63+
changed.
64+
- [ ] Document the policy in the workflow comments so the rationale remains obvious.
65+
66+
### Task 2: Add a dedicated lightweight docs workflow
67+
68+
- [ ] Create a workflow dedicated to documentation validation.
69+
- [ ] Run only the documentation-relevant checks, at minimum markdownlint and `cspell`.
70+
- [ ] Keep the workflow lightweight. Using the internal `linter` binary is acceptable if its
71+
installation and execution cost stays low enough for documentation-only pull requests.
72+
- [ ] Ensure the workflow is fast enough to serve as the main required signal for docs-only pull
73+
requests.
74+
75+
### Task 3: Exclude docs-only changes from heavyweight workflows
76+
77+
- [ ] Update the heavyweight PR workflows so docs-only changes do not run the full CI matrix.
78+
- [ ] Update branch protection rules so skipped heavyweight workflows do not block
79+
documentation-only pull requests.
80+
- [ ] Verify behavior for `pull_request` and, if needed, `push` events.
81+
- [ ] Confirm that docs-only pull requests remain mergeable.
82+
83+
### Task 4: Validate mixed-change behavior
84+
85+
- [ ] Verify that a pull request touching both docs and Rust code still runs the full CI set.
86+
- [ ] Verify that a pull request touching docs plus workflow files still runs the appropriate CI.
87+
- [ ] Document at least one representative example for each case.
88+
89+
## Acceptance Criteria
90+
91+
- [ ] Documentation-only pull requests do not run heavyweight test and E2E workflows.
92+
- [ ] Documentation-only pull requests still run markdownlint and `cspell` in CI.
93+
- [ ] The docs-only workflow remains lightweight enough for documentation-only pull requests,
94+
including when implemented via the internal `linter` binary.
95+
- [ ] Pull requests that touch code continue to run the full relevant CI workflows.
96+
- [ ] Branch protection rules are adjusted so docs-only pull requests are not blocked by skipped
97+
heavyweight workflows.
98+
- [ ] Workflow comments document the path policy clearly.
99+
100+
## References
101+
102+
- Related workflow: [`.github/workflows/testing.yaml`](../../../.github/workflows/testing.yaml)
103+
- Related workflow: [`.github/workflows/os-compatibility.yaml`](../../../.github/workflows/os-compatibility.yaml)
104+
- Related workflow: [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
105+
- Related workflow: [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)
106+
- Related EPIC: [docs/issues/1742-ci-change-aware-workflows-epic.md](./1742-ci-change-aware-workflows-epic.md)
107+
- Related issue: [#1726](https://github.com/torrust/torrust-tracker/issues/1726) (research on
108+
reducing the cost of workflows that still need to run)
109+
- Related local spec: [docs/issues/1740-fix-container-workflow-caching.md](./1740-fix-container-workflow-caching.md)

‎docs/issues/1744-scope-persistence-workflows-by-path.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Scope Persistence Workflows by Path
2+
3+
## Goal
4+
5+
Run persistence-specific CI workflows only when a pull request changes files that can affect
6+
database compatibility or persistence benchmarking.
7+
8+
## Problem
9+
10+
The following workflows currently run broadly on most pull requests:
11+
12+
- [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
13+
- [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)
14+
15+
Both workflows are persistence-specific. They validate database compatibility and benchmark the
16+
`bittorrent-tracker-core` persistence layer, but they currently run even when a pull request only
17+
changes unrelated areas such as documentation, HTTP client code, or other non-persistence
18+
packages.
19+
20+
That wastes CI time and runner capacity without increasing confidence.
21+
22+
Issue [#1726](https://github.com/torrust/torrust-tracker/issues/1726) may reduce the runtime cost
23+
of these workflows later, but it does not change the fact that they should not run for unrelated
24+
pull requests.
25+
26+
## Scope Decision
27+
28+
This issue should intentionally scope the persistence workflows to changes in `tracker-core`,
29+
because the workflows are validating the persistence implementation directly.
30+
31+
The database compatibility jobs in
32+
[`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
33+
run `cargo test -p bittorrent-tracker-core ... run_mysql_driver_tests` and
34+
`run_postgres_driver_tests`. Those tests construct the database drivers and call the persistence
35+
methods directly against real database instances.
36+
37+
Because of that, the intent of these workflows is narrower than general workspace regression
38+
coverage: they are primarily checking schema, migration, query, and persistence-driver behavior in
39+
`tracker-core`.
40+
41+
The preferred trigger scope for this issue is therefore:
42+
43+
- `packages/tracker-core/**`
44+
- the workflow files themselves when they are modified
45+
46+
General compile or cross-package integration regressions remain the responsibility of the broader
47+
testing workflows.
48+
49+
This issue should also avoid depending on the outcome of `#1726`. Even if `sccache` proves useful,
50+
running persistence workflows for unrelated changes would still be wasteful.
51+
52+
## Proposed Changes
53+
54+
### Task 1: Define the persistence-relevant path set
55+
56+
- [ ] Define the narrow path set for persistence workflows, centered on `packages/tracker-core/**`.
57+
- [ ] Decide whether workflow file changes should also trigger the workflows.
58+
- [ ] Document explicitly that this is an intentional optimization tradeoff, not full dependency
59+
closure analysis.
60+
61+
### Task 2: Restrict the database compatibility workflow
62+
63+
- [ ] Update [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
64+
so it only runs for persistence-relevant changes.
65+
- [ ] Validate behavior for both MySQL and PostgreSQL jobs.
66+
- [ ] Confirm that required-check behavior remains mergeable for unrelated pull requests.
67+
68+
### Task 3: Restrict the persistence benchmarking workflow
69+
70+
- [ ] Update [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)
71+
so it only runs for persistence-relevant changes.
72+
- [ ] Ensure the path policy stays aligned with the compatibility workflow.
73+
- [ ] Confirm that unrelated pull requests no longer trigger the benchmarking workflow.
74+
75+
### Task 4: Add guardrails for future dependency drift
76+
77+
- [ ] Add comments near the trigger rules explaining that the scope is intentionally limited to
78+
tracker-core persistence changes.
79+
- [ ] Consider whether workflow file changes should bypass the path filter.
80+
- [ ] Verify at least one negative case and one positive case with representative pull requests.
81+
82+
## Acceptance Criteria
83+
84+
- [ ] `db-compatibility` does not run for unrelated pull requests.
85+
- [ ] `db-benchmarking` does not run for unrelated pull requests.
86+
- [ ] Both workflows run when `packages/tracker-core/**` changes.
87+
- [ ] The trigger rules are documented and maintainable.
88+
- [ ] Required-check behavior does not leave unrelated pull requests blocked.
89+
90+
## References
91+
92+
- Related workflow: [`.github/workflows/db-compatibility.yaml`](../../../.github/workflows/db-compatibility.yaml)
93+
- Related workflow: [`.github/workflows/db-benchmarking.yaml`](../../../.github/workflows/db-benchmarking.yaml)
94+
- Related EPIC: [docs/issues/1742-ci-change-aware-workflows-epic.md](./1742-ci-change-aware-workflows-epic.md)
95+
- Related issue: [#1726](https://github.com/torrust/torrust-tracker/issues/1726) (complementary
96+
build-time research, not a blocker for this change)

0 commit comments

Comments
 (0)