Skip to content

Commit 592c46c

Browse files
CybotTMCybotTM
committed
[TASK] Add documentation, README, and architecture decision records
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
1 parent f9483b3 commit 592c46c

14 files changed

Lines changed: 759 additions & 2 deletions

‎Documentation/Decisions/ADR-001-SharedWorkflows.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. include:: /Includes.rst.txt
2+
3+
===========================================
4+
ADR-001: Use Shared Reusable Workflows
5+
===========================================
6+
7+
Status
8+
======
9+
Accepted
10+
11+
Context
12+
=======
13+
The TYPO3 Documentation organization maintains ~29 repositories with similar
14+
CI/CD workflows. Each repository maintained its own inline workflow definitions,
15+
leading to:
16+
17+
* **Maintenance burden** — Action version updates required touching every repo
18+
* **Inconsistency** — Repos drifted apart in configuration
19+
* **Incident amplification** — A broken action (e.g. ``m-kuhn/backport@30b6e83``
20+
missing ``dist/index.js``) required individual fixes in each repo
21+
* **Allow-list compliance** — The org enforces SHA-pinned actions; composite
22+
actions like ``ramsey/composer-install`` that internally use tag references
23+
break all CI runs
24+
25+
Decision
26+
========
27+
Centralize common CI/CD patterns as `reusable workflows
28+
<https://docs.github.com/en/actions/sharing-automations/reusing-workflows>`__
29+
in a single org-owned repository.
30+
31+
Reusable workflows:
32+
33+
* Execute in their own context, bypassing the caller's action allow-list
34+
* Provide a single point for action SHA pin management
35+
* Accept inputs for repo-specific configuration while enforcing consistent
36+
defaults
37+
38+
Consequences
39+
============
40+
* **Positive:** One-place updates for action versions, consistent behavior,
41+
faster incident response
42+
* **Positive:** Calling repos need only a few lines of YAML
43+
* **Negative:** Added indirection — debugging requires looking at two repos
44+
* **Negative:** Breaking changes in shared workflows affect all consumers
45+
* **Mitigation:** Use ``@main`` ref with careful review; consider tags for
46+
stability later

‎Documentation/Decisions/ADR-002-DotGithubRepo.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
.. include:: /Includes.rst.txt
2+
3+
============================================
4+
ADR-002: Use .github Repo for Shared Workflows
5+
============================================
6+
7+
Status
8+
======
9+
Accepted (supersedes initial placement in t3docs-ci-deploy)
10+
11+
Context
12+
=======
13+
The shared reusable workflows were initially placed in
14+
``TYPO3-Documentation/t3docs-ci-deploy`` (the existing CI/CD pipeline repo).
15+
This required adding ``t3docs-ci-deploy`` to the org's GitHub Actions allow-list
16+
for reusable workflow calls.
17+
18+
GitHub provides a special ``.github`` repository per organization that serves as
19+
the "community health" repo. Reusable workflows placed there are automatically
20+
available to all repositories in the organization without any allow-list
21+
configuration.
22+
23+
Decision
24+
========
25+
Move shared reusable workflows from ``t3docs-ci-deploy`` to
26+
``TYPO3-Documentation/.github``.
27+
28+
This was proposed by @jaapio and implemented by @linawolf.
29+
30+
Consequences
31+
============
32+
* **Positive:** No org admin action needed — workflows are automatically trusted
33+
* **Positive:** ``.github`` is the GitHub-conventional location for org-wide
34+
shared resources (also hosts community health files like CODE_OF_CONDUCT)
35+
* **Positive:** Clear separation — ``t3docs-ci-deploy`` remains focused on
36+
build/deploy pipelines
37+
* **Negative:** The ``.github`` repo has a special role; mixing workflows with
38+
community health files may cause confusion
39+
* **Mitigation:** Clear documentation and README explaining the repo's dual purpose

‎Documentation/Decisions/Index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. include:: /Includes.rst.txt
2+
3+
======================
4+
Architecture Decisions
5+
======================
6+
7+
This section documents significant architectural decisions using the
8+
`ADR (Architecture Decision Record) <https://adr.github.io/>`__ format.
9+
10+
.. toctree::
11+
:titlesonly:
12+
13+
ADR-001-SharedWorkflows
14+
ADR-002-DotGithubRepo

‎Documentation/Includes.rst.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.. This file is included in all RST files to provide common definitions.
2+
3+
.. |project_name| replace:: TYPO3 Documentation Shared Workflows

‎Documentation/Index.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
.. include:: /Includes.rst.txt
2+
3+
========================================
4+
TYPO3 Documentation — Shared Workflows
5+
========================================
6+
7+
.. contents:: Table of Contents
8+
:depth: 2
9+
:local:
10+
11+
Introduction
12+
============
13+
14+
This repository provides shared reusable GitHub Actions workflows for the
15+
`TYPO3 Documentation <https://github.com/TYPO3-Documentation>`__ organization.
16+
17+
By centralizing workflow definitions, documentation repositories benefit from:
18+
19+
* **Single point of maintenance** — Action versions and configurations are
20+
updated in one place.
21+
* **Consistent behavior** — All repositories that adopt these workflows
22+
behave identically.
23+
* **Reduced boilerplate** — Calling repos need only a few lines of YAML
24+
instead of duplicating entire job definitions.
25+
26+
.. toctree::
27+
:caption: Workflows
28+
:titlesonly:
29+
30+
Workflows/Backport
31+
Workflows/TestDocumentation
32+
Workflows/ApplyPrecommit
33+
Workflows/PhpQuality
34+
Workflows/PhpTests
35+
Workflows/PhpCommand
36+
Workflows/DocsRender
37+
38+
.. toctree::
39+
:caption: Architecture Decisions
40+
:titlesonly:
41+
42+
Decisions/Index
43+
44+
Migration Guide
45+
===============
46+
47+
To migrate an existing inline workflow to a shared reusable workflow:
48+
49+
1. Identify which shared workflow matches your current inline job.
50+
2. Replace the ``jobs:`` section with a ``uses:`` call to the shared workflow.
51+
3. Pass any required inputs via ``with:``.
52+
4. Remove inline ``permissions:``, ``steps:``, and ``runs-on:`` — these are
53+
defined in the shared workflow.
54+
55+
.. code-block:: yaml
56+
:caption: Example: Migrating backport workflow
57+
58+
# Before (inline)
59+
jobs:
60+
backport:
61+
if: github.event.pull_request.merged == true
62+
runs-on: ubuntu-latest
63+
steps:
64+
- uses: actions/checkout@...
65+
- uses: korthout/backport-action@...
66+
67+
# After (shared)
68+
jobs:
69+
backport:
70+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-backport.yml@main

‎Documentation/Workflows/ApplyPrecommit.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. include:: /Includes.rst.txt
2+
3+
================
4+
Apply Pre-commit
5+
================
6+
7+
The **Apply Pre-commit** workflow runs `pre-commit <https://pre-commit.com>`__
8+
hooks across the entire repository and, if any files are modified, opens a pull
9+
request with the fixes. It is designed to be called on a schedule so that
10+
whitespace and formatting issues are cleaned up automatically.
11+
12+
The workflow only runs in repositories owned by the ``TYPO3-Documentation``
13+
organization.
14+
15+
Inputs
16+
------
17+
18+
.. csv-table::
19+
:header: "Input", "Type", "Default", "Description"
20+
21+
"python-version", "string", "``3.x``", "Python version used to run pre-commit."
22+
"pr-title", "string", "``Fix whitespace issues``", "Title of the auto-generated pull request."
23+
"pr-body", "string", "``This PR automatically applies whitespace fixes.``", "Body text of the auto-generated pull request."
24+
25+
Permissions
26+
-----------
27+
28+
The workflow requires the following permissions in the calling repository:
29+
30+
* ``contents: write``
31+
* ``pull-requests: write``
32+
33+
Usage
34+
-----
35+
36+
.. code-block:: yaml
37+
:caption: .github/workflows/apply-precommit.yml
38+
39+
name: Apply pre-commit fixes
40+
on:
41+
schedule:
42+
- cron: '0 4 * * 1'
43+
44+
jobs:
45+
precommit:
46+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-apply-precommit.yml@main
47+
with:
48+
python-version: "3.x"
49+
pr-title: "Fix whitespace issues"
50+
pr-body: "This PR automatically applies whitespace fixes."
51+
52+
Behavior
53+
--------
54+
55+
1. Pre-commit hooks run with ``--all-files --hook-stage=manual``.
56+
2. If any files are changed, the workflow checks for an existing open PR with
57+
the same title to avoid duplicates.
58+
3. A new branch ``fix/whitespace-<timestamp>`` is created and pushed.
59+
4. A pull request targeting the triggering branch is opened automatically.

‎Documentation/Workflows/Backport.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.. include:: /Includes.rst.txt
2+
3+
========
4+
Backport
5+
========
6+
7+
The **Backport** workflow automatically creates backport pull requests when a
8+
merged PR carries a matching label (e.g. ``backport v12``).
9+
10+
It uses the `korthout/backport-action <https://github.com/korthout/backport-action>`__
11+
under the hood and is intended to be called from a ``pull_request_target`` event.
12+
13+
Inputs
14+
------
15+
16+
.. csv-table::
17+
:header: "Input", "Type", "Default", "Description"
18+
19+
"label_pattern", "string", "``^backport ([^ ]+)$``", "Regex pattern to match backport labels. Must contain a capture group for the target branch."
20+
21+
The capture group in the regex pattern is used as the target branch name. For
22+
example, a label ``backport v12`` with the default pattern ``^backport ([^ ]+)$``
23+
triggers a backport to the ``v12`` branch.
24+
25+
Secrets
26+
-------
27+
28+
.. csv-table::
29+
:header: "Secret", "Required", "Description"
30+
31+
"APP_ID", "no", "GitHub App ID for creating backport pull requests"
32+
"APP_PRIVATE_KEY", "no", "GitHub App private key (PEM format)"
33+
34+
Pull requests created with the default ``GITHUB_TOKEN`` do not trigger CI
35+
workflows on the resulting backport PR. Passing a GitHub App token ensures that
36+
backport PRs trigger their own CI checks (tests, linting, etc.).
37+
38+
If neither secret is provided the workflow falls back to the default
39+
``GITHUB_TOKEN``.
40+
41+
Permissions
42+
-----------
43+
44+
The workflow requires the following permissions in the calling repository:
45+
46+
* ``contents: write``
47+
* ``pull-requests: write``
48+
49+
Usage
50+
-----
51+
52+
.. code-block:: yaml
53+
:caption: .github/workflows/backport.yml
54+
55+
name: Backport
56+
on:
57+
pull_request_target:
58+
types: [closed]
59+
60+
jobs:
61+
backport:
62+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-backport.yml@main
63+
with:
64+
label_pattern: "^backport ([^ ]+)$"
65+
secrets:
66+
APP_ID: ${{ secrets.APP_ID }}
67+
APP_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }}

‎Documentation/Workflows/DocsRender.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. include:: /Includes.rst.txt
2+
3+
=======================
4+
Documentation Rendering
5+
=======================
6+
7+
The **Documentation Rendering** workflow renders TYPO3 documentation using
8+
either the Python-based ``typo3-docs-theme`` or the Composer-based
9+
``typo3/guides-cli``, depending on which is available in the project.
10+
11+
The workflow automatically detects the rendering tool:
12+
13+
* If ``composer.json`` contains ``typo3/guides-cli``, Composer dependencies are
14+
installed and ``vendor/bin/guides`` is used.
15+
* Otherwise, ``typo3-docs-theme`` is installed via pip and used to render.
16+
17+
Inputs
18+
------
19+
20+
.. csv-table::
21+
:header: "Input", "Type", "Default", "Description"
22+
23+
"python-version", "string", "``3.12``", "Python version used when rendering via ``typo3-docs-theme``."
24+
25+
Usage
26+
-----
27+
28+
.. code-block:: yaml
29+
:caption: .github/workflows/docs-render.yml
30+
31+
name: Render documentation
32+
on: [push, pull_request]
33+
34+
jobs:
35+
render:
36+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-docs-render.yml@main
37+
with:
38+
python-version: "3.12"

‎Documentation/Workflows/PhpCommand.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
.. include:: /Includes.rst.txt
2+
3+
===========
4+
PHP Command
5+
===========
6+
7+
The **PHP Command** workflow is a generic building block that sets up PHP,
8+
installs Composer dependencies, and runs a single arbitrary command. It is useful
9+
for one-off tasks that do not fit the specialized quality or test workflows —
10+
for example generating API documentation, running database migrations, or
11+
executing custom scripts.
12+
13+
Inputs
14+
------
15+
16+
.. csv-table::
17+
:header: "Input", "Type", "Default", "Description"
18+
19+
"php-version", "string", "``8.2``", "PHP version to install."
20+
"command", "string", "*(required)*", "Command to run after ``composer install``."
21+
"php-extensions", "string", "``""""``", "Space-separated PHP extensions to install."
22+
"composer-args", "string", "``--no-interaction --no-progress --prefer-dist``", "Arguments passed to ``composer install``."
23+
"run-environment", "string", "``local``", "Value of the ``RUN_ENVIRONMENT`` env variable."
24+
25+
Usage
26+
-----
27+
28+
.. code-block:: yaml
29+
:caption: .github/workflows/generate-docs.yml
30+
31+
name: Generate API docs
32+
on: [push]
33+
34+
jobs:
35+
generate:
36+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-php-command.yml@main
37+
with:
38+
php-version: "8.3"
39+
command: "vendor/bin/generate-api-docs"
40+
41+
Custom Composer Arguments
42+
-------------------------
43+
44+
Override the default Composer arguments when you need dev dependencies or a
45+
different install strategy:
46+
47+
.. code-block:: yaml
48+
49+
with:
50+
command: "vendor/bin/rector process --dry-run"
51+
composer-args: "--no-interaction --no-progress"

0 commit comments

Comments
 (0)