Skip to content

Commit 444d896

Browse files
CybotTMCybotTM
committed
[TASK] Add TYPO3-style RST documentation for shared workflows
1 parent bfd07dd commit 444d896

9 files changed

Lines changed: 369 additions & 0 deletions

File tree

‎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: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
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/DocsRender
36+
37+
Migration Guide
38+
===============
39+
40+
To migrate an existing inline workflow to a shared reusable workflow:
41+
42+
1. Identify which shared workflow matches your current inline job.
43+
2. Replace the ``jobs:`` section with a ``uses:`` call to the shared workflow.
44+
3. Pass any required inputs via ``with:``.
45+
4. Remove inline ``permissions:``, ``steps:``, and ``runs-on:`` — these are
46+
defined in the shared workflow.
47+
48+
.. code-block:: yaml
49+
:caption: Example: Migrating backport workflow
50+
51+
# Before (inline)
52+
jobs:
53+
backport:
54+
if: github.event.pull_request.merged == true
55+
runs-on: ubuntu-latest
56+
steps:
57+
- uses: actions/checkout@...
58+
- uses: korthout/backport-action@...
59+
60+
# After (shared)
61+
jobs:
62+
backport:
63+
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: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
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 *``", "Glob pattern matched against PR labels to determine target branches."
20+
21+
The wildcard portion of the 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+
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/backport.yml
38+
39+
name: Backport
40+
on:
41+
pull_request_target:
42+
types: [closed]
43+
44+
jobs:
45+
backport:
46+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-backport.yml@main
47+
with:
48+
label_pattern: "backport *"

‎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/PhpQuality.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
.. include:: /Includes.rst.txt
2+
3+
===========
4+
PHP Quality
5+
===========
6+
7+
The **PHP Quality** workflow runs static analysis tools — PHP CS Fixer, PHPStan,
8+
and optionally XML linting — against a PHP project. Each tool can be toggled on
9+
or off and its invocation command customized.
10+
11+
Inputs
12+
------
13+
14+
.. csv-table::
15+
:header: "Input", "Type", "Default", "Description"
16+
17+
"php-version", "string", "``8.2``", "PHP version for quality checks."
18+
"run-cs-fixer", "boolean", "``true``", "Whether to run PHP CS Fixer."
19+
"cs-fixer-command", "string", "``make test-cs-fixer``", "Command to invoke PHP CS Fixer."
20+
"run-phpstan", "boolean", "``true``", "Whether to run PHPStan."
21+
"phpstan-command", "string", "``make test-phpstan``", "Command to invoke PHPStan."
22+
"run-xml-lint", "boolean", "``false``", "Whether to run XML linting."
23+
"xml-lint-command", "string", "``make test-xml-lint``", "Command to invoke XML linting."
24+
"php-extensions", "string", "``""""``", "Space-separated PHP extensions to install."
25+
"run-environment", "string", "``local``", "Value of the ``RUN_ENVIRONMENT`` env variable passed to each tool."
26+
27+
Usage
28+
-----
29+
30+
.. code-block:: yaml
31+
:caption: .github/workflows/php-quality.yml
32+
33+
name: PHP Quality
34+
on: [push, pull_request]
35+
36+
jobs:
37+
quality:
38+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-php-quality.yml@main
39+
with:
40+
php-version: "8.2"
41+
run-cs-fixer: true
42+
run-phpstan: true
43+
run-xml-lint: false
44+
45+
Customizing Commands
46+
--------------------
47+
48+
By default the workflow expects ``make`` targets in the consuming repository.
49+
Override the command inputs to use different tooling:
50+
51+
.. code-block:: yaml
52+
53+
with:
54+
cs-fixer-command: "vendor/bin/php-cs-fixer fix --dry-run --diff"
55+
phpstan-command: "vendor/bin/phpstan analyse --no-progress"

‎Documentation/Workflows/PhpTests.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+
PHP Tests
5+
=========
6+
7+
The **PHP Tests** workflow runs unit and integration tests across a matrix of
8+
PHP versions. The matrix is defined as a JSON array, allowing callers to test
9+
against any combination of PHP releases.
10+
11+
Inputs
12+
------
13+
14+
.. csv-table::
15+
:header: "Input", "Type", "Default", "Description"
16+
17+
"php-versions", "string (JSON)", "``[""8.2"", ""8.3"", ""8.4"", ""8.5""]``", "JSON array of PHP versions to test against."
18+
"dependency-versions", "string", "``locked``", "Composer dependency resolution strategy (``locked``, ``highest``, or ``lowest``)."
19+
"test-unit-command", "string", "``make test-unit``", "Command to run unit tests. Set empty to skip."
20+
"test-integration-command", "string", "``""""``", "Command to run integration tests. Leave empty to skip."
21+
"php-extensions", "string", "``""""``", "Space-separated PHP extensions to install."
22+
"run-environment", "string", "``local``", "Value of the ``RUN_ENVIRONMENT`` env variable."
23+
24+
Usage
25+
-----
26+
27+
.. code-block:: yaml
28+
:caption: .github/workflows/php-tests.yml
29+
30+
name: PHP Tests
31+
on: [push, pull_request]
32+
33+
jobs:
34+
tests:
35+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-php-tests.yml@main
36+
with:
37+
php-versions: '["8.2", "8.3", "8.4"]'
38+
test-unit-command: "make test-unit"
39+
test-integration-command: "make test-integration"
40+
41+
Matrix Strategy
42+
---------------
43+
44+
The workflow uses ``fail-fast: false`` so that a failure in one PHP version does
45+
not cancel the remaining matrix jobs. This ensures you get a complete picture of
46+
compatibility across all targeted versions.

‎Documentation/Workflows/TestDocumentation.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. include:: /Includes.rst.txt
2+
3+
==================
4+
Test Documentation
5+
==================
6+
7+
The **Test Documentation** workflow renders the project documentation inside a
8+
Docker container using the official
9+
`render-guides <https://github.com/TYPO3-Documentation/render-guides>`__ image.
10+
It verifies that documentation builds without warnings and can optionally be
11+
restricted to a specific repository when triggered on a schedule.
12+
13+
Inputs
14+
------
15+
16+
.. csv-table::
17+
:header: "Input", "Type", "Default", "Description"
18+
19+
"render-flags", "string", "``--no-progress --minimal-test``", "Additional flags passed to ``render-guides`` (e.g. ``--fail-on-log``)."
20+
"schedule-repository", "string", "``""""``", "Repository name to restrict scheduled runs. Leave empty to always run."
21+
22+
Usage
23+
-----
24+
25+
.. code-block:: yaml
26+
:caption: .github/workflows/test-documentation.yml
27+
28+
name: Test documentation
29+
on:
30+
push:
31+
branches:
32+
- main
33+
pull_request:
34+
schedule:
35+
- cron: '0 6 * * 1'
36+
37+
jobs:
38+
test-docs:
39+
uses: TYPO3-Documentation/.github/.github/workflows/reusable-test-documentation.yml@main
40+
with:
41+
render-flags: "--no-progress --fail-on-log"
42+
schedule-repository: "TYPO3-Documentation/my-docs"
43+
44+
Schedule Filtering
45+
------------------
46+
47+
When the workflow is triggered via ``schedule``, the ``schedule-repository``
48+
input can limit execution to a single repository. This is useful when a shared
49+
workflow file is inherited by many forks but the scheduled run should only
50+
execute in the upstream repository.

‎Documentation/guides.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<guides xmlns="https://www.phpdoc.org/guides"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="https://www.phpdoc.org/guides https://www.phpdoc.org/guides/guides.xsd"
5+
>
6+
<project title="TYPO3 Documentation Shared Workflows"/>
7+
</guides>

0 commit comments

Comments
 (0)