Skip to content

Commit c9cfd2c

Browse files
coisacoisa
committed
Add comprehensive documentation updates and new FAQ section
- Introduced a new FAQ document covering common issues and questions related to the FastForward DevTools package. - Revised the Getting Started guide to clarify installation steps and initial commands. - Expanded the Installation section with detailed requirements and post-installation behavior. - Added a Quickstart guide for rapid onboarding of new libraries. - Updated Supported PHP Versions documentation to reflect compatibility with PHP 8.3 and newer. - Enhanced the Architecture and Command Lifecycle section to explain local command execution and consumer synchronization. - Created a new Links section consolidating external references and project dependencies. - Added detailed reports generation instructions and clarified the purpose of the reports command. - Documented specialized commands for testing, code style auditing, automated refactoring, and documentation generation. - Introduced common workflows and documentation workflows to guide users in daily tasks. - Added troubleshooting tips for documentation generation failures. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
1 parent 0126601 commit c9cfd2c

33 files changed

Lines changed: 1284 additions & 189 deletions

‎docs/advanced/consumer-automation.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Consumer Automation
2+
===================
3+
4+
FastForward DevTools plays two roles at once:
5+
6+
- producer: this repository ships reusable workflow templates and default
7+
configuration files;
8+
- consumer helper: the ``dev-tools:sync`` command copies those assets into
9+
other Fast Forward libraries.
10+
11+
Reusable Workflows Versus Consumer Stubs
12+
----------------------------------------
13+
14+
.. list-table::
15+
:header-rows: 1
16+
17+
* - Location
18+
- Role
19+
* - ``.github/workflows/*.yml``
20+
- Reusable workflows implemented in this repository.
21+
* - ``resources/github-actions/*.yml``
22+
- Small consumer stubs that call the reusable workflows through
23+
``workflow_call``.
24+
* - ``.github/dependabot.yml``
25+
- This repository's own Dependabot configuration.
26+
* - ``resources/dependabot.yml``
27+
- Template copied into consumer repositories.
28+
* - ``.github/wiki``
29+
- Generated Markdown API documentation locally and wiki submodule content
30+
in consumer repositories.
31+
32+
How GitHub Pages Publishing Works
33+
---------------------------------
34+
35+
- ``.github/workflows/reports.yml`` runs ``composer dev-tools reports``.
36+
- The workflow uploads ``public/`` as the Pages artifact.
37+
- On the ``main`` branch, GitHub Pages serves the generated site.
38+
39+
How Wiki Publishing Works
40+
-------------------------
41+
42+
- ``.github/workflows/wiki.yml`` runs
43+
``composer dev-tools wiki -- --target=.github/wiki``.
44+
- The workflow commits the wiki submodule contents.
45+
- The parent repository then commits the updated submodule pointer.
46+
47+
Producer Impact
48+
---------------
49+
50+
Any change to ``resources/github-actions``, ``resources/dependabot.yml``,
51+
``.github/workflows``, or ``FastForward\DevTools\Command\SyncCommand`` changes
52+
the default onboarding story for every consumer library.

‎docs/advanced/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Advanced
2+
========
3+
4+
This section explains the package features that are easy to miss when you only
5+
run the public commands: reusable automation, the PHPUnit extension, and the
6+
custom Rector and PHPDoc behavior.
7+
8+
.. toctree::
9+
:maxdepth: 1
10+
11+
consumer-automation
12+
phpunit-extension
13+
rector-and-phpdoc

‎docs/advanced/phpunit-extension.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
PHPUnit Extension
2+
=================
3+
4+
The packaged ``phpunit.xml`` is intentionally opinionated. Besides enabling
5+
strict PHPUnit flags, it registers
6+
``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
7+
8+
Runtime Chain
9+
-------------
10+
11+
1. ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``
12+
registers a tracer and two subscribers with PHPUnit.
13+
2. ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``
14+
enables ``DG\BypassFinals`` at suite start.
15+
3. ``FastForward\DevTools\PhpUnit\Event\EventTracer`` records the events
16+
emitted during the run.
17+
4. ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
18+
builds a summary notification and sends it when the run finishes.
19+
20+
Why This Helps Consumer Projects
21+
--------------------------------
22+
23+
- tests can double final classes and final methods when the test environment
24+
needs it;
25+
- developers get a quick desktop summary without reading the full terminal
26+
scrollback;
27+
- event counts are available to the notification layer without adding ad-hoc
28+
test code.
29+
30+
What to Remember When Overriding ``phpunit.xml``
31+
------------------------------------------------
32+
33+
If a consumer project replaces the packaged ``phpunit.xml``, it also replaces
34+
this extension unless it re-registers it manually. That is usually fine, but
35+
it explains why notifications or BypassFinals behavior may disappear after a
36+
local override.
37+
38+
.. note::
39+
40+
The notification subscriber still works when ``pcntl_fork()`` is
41+
unavailable. Forking only makes notification delivery less blocking on
42+
platforms that support it.

‎docs/advanced/rector-and-phpdoc.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Rector and PHPDoc Automation
2+
============================
3+
4+
The package uses two different Rector entry points, and that difference matters
5+
when you are trying to understand why a rule did or did not run.
6+
7+
``refactor`` Versus ``phpdoc``
8+
------------------------------
9+
10+
- ``refactor`` uses the full ``rector.php`` file.
11+
- ``phpdoc`` runs PHP-CS-Fixer first and then executes Rector with
12+
``--only \FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``.
13+
14+
Rules Shipped by the Package
15+
----------------------------
16+
17+
.. list-table::
18+
:header-rows: 1
19+
20+
* - Rule
21+
- Enabled in packaged ``rector.php``
22+
- Used directly by ``phpdoc``
23+
- Purpose
24+
* - ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``
25+
- Yes
26+
- Yes
27+
- Adds ``@param``, ``@return``, and ``@throws`` tags when they can be
28+
inferred.
29+
* - ``FastForward\DevTools\Rector\RemoveEmptyDocBlockRector``
30+
- Yes
31+
- No
32+
- Removes empty docblocks left behind by refactors.
33+
* - ``FastForward\DevTools\Rector\AddMissingClassPhpDocRector``
34+
- No
35+
- No
36+
- Available for projects that want to opt in manually.
37+
38+
Other Packaged Rector Behavior
39+
------------------------------
40+
41+
The default ``rector.php`` also loads shared Rector sets, imports names,
42+
removes unused imports, skips generated directories, and enables Safe migration
43+
rules when ``thecodingmachine/safe`` is installed.
44+
45+
Why ``.docheader`` Appears Automatically
46+
----------------------------------------
47+
48+
The ``phpdoc`` command creates ``.docheader`` in the consumer root when it is
49+
missing. The template comes from the packaged file and the package name is
50+
rewritten to match the current project whenever Composer metadata is
51+
available.

‎docs/api/commands.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Command Classes
2+
===============
3+
4+
All public CLI commands extend
5+
``FastForward\DevTools\Command\AbstractCommand``, which provides path
6+
resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
7+
8+
.. list-table::
9+
:header-rows: 1
10+
11+
* - Class
12+
- CLI command
13+
- Responsibility
14+
* - ``FastForward\DevTools\Command\AbstractCommand``
15+
- n/a
16+
- Shared helpers for path resolution, packaged fallback files, PSR-4
17+
discovery, and subcommand execution.
18+
* - ``FastForward\DevTools\Command\StandardsCommand``
19+
- ``standards``
20+
- Runs the full quality pipeline.
21+
* - ``FastForward\DevTools\Command\RefactorCommand``
22+
- ``refactor``
23+
- Runs Rector with local or packaged configuration.
24+
* - ``FastForward\DevTools\Command\PhpDocCommand``
25+
- ``phpdoc``
26+
- Runs PHP-CS-Fixer and a focused Rector PHPDoc pass.
27+
* - ``FastForward\DevTools\Command\CodeStyleCommand``
28+
- ``code-style``
29+
- Runs Composer Normalize and ECS.
30+
* - ``FastForward\DevTools\Command\TestsCommand``
31+
- ``tests``
32+
- Runs PHPUnit with optional coverage output.
33+
* - ``FastForward\DevTools\Command\DocsCommand``
34+
- ``docs``
35+
- Builds the HTML documentation site.
36+
* - ``FastForward\DevTools\Command\WikiCommand``
37+
- ``wiki``
38+
- Builds Markdown API documentation.
39+
* - ``FastForward\DevTools\Command\ReportsCommand``
40+
- ``reports``
41+
- Combines the documentation build with coverage generation.
42+
* - ``FastForward\DevTools\Command\SyncCommand``
43+
- ``dev-tools:sync``
44+
- Synchronizes consumer-facing scripts and automation assets.

‎docs/api/composer-integration.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
Composer Integration
2+
====================
3+
4+
FastForward DevTools is exposed through both a Composer plugin and a dedicated
5+
console application.
6+
7+
Startup Chain
8+
-------------
9+
10+
1. ``bin/dev-tools`` loads ``bin/dev-tools.php``.
11+
2. ``bin/dev-tools.php`` prefers the consumer project's
12+
``vendor/autoload.php`` and falls back to the package autoloader.
13+
3. ``bin/dev-tools.php`` starts ``FastForward\DevTools\DevTools`` and appends
14+
``--no-plugins``.
15+
4. ``FastForward\DevTools\DevTools`` sets ``standards`` as the default command
16+
and loads commands from
17+
``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``.
18+
19+
Composer Plugin Classes
20+
-----------------------
21+
22+
.. list-table::
23+
:header-rows: 1
24+
25+
* - Class
26+
- Purpose
27+
* - ``FastForward\DevTools\Composer\Plugin``
28+
- Registers the command provider and runs ``dev-tools:sync`` after
29+
Composer install and update.
30+
* - ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``
31+
- Instantiates and returns the available command classes.
32+
* - ``FastForward\DevTools\DevTools``
33+
- Console application used by the local binary.
34+
35+
Why ``--no-plugins`` Is Appended
36+
--------------------------------
37+
38+
The local binary already knows which commands it needs. Appending
39+
``--no-plugins`` keeps the standalone application predictable and avoids
40+
pulling unrelated Composer plugins into the command runtime.

‎docs/api/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
API Overview
2+
============
3+
4+
This section maps the main classes that make FastForward DevTools work. It is
5+
useful when you need to navigate the codebase, debug consumer behavior, or
6+
document extension points precisely.
7+
8+
.. toctree::
9+
:maxdepth: 1
10+
11+
commands
12+
composer-integration
13+
phpunit-support
14+
rector-rules

‎docs/api/phpunit-support.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
PHPUnit Support Classes
2+
=======================
3+
4+
The packaged test configuration includes a small integration layer under
5+
``FastForward\DevTools\PhpUnit``.
6+
7+
.. list-table::
8+
:header-rows: 1
9+
10+
* - Class
11+
- Role
12+
- Notes
13+
* - ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``
14+
- Registers tracer and subscribers
15+
- Wired through ``phpunit.xml``.
16+
* - ``FastForward\DevTools\PhpUnit\Event\EventTracer``
17+
- Stores PHPUnit events by class name
18+
- Used to build notification summaries.
19+
* - ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``
20+
- Enables ``DG\BypassFinals``
21+
- Allows tests to work with final constructs.
22+
* - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
23+
- Sends desktop notifications
24+
- Summarizes pass, failure, error, runtime, and memory data.
25+
26+
These classes are especially relevant when a consumer project overrides the
27+
packaged ``phpunit.xml`` and wants to preserve the same runtime behavior.

‎docs/api/rector-rules.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Rector Rules
2+
============
3+
4+
FastForward DevTools ships custom Rector rules in ``src/Rector/`` to support
5+
the PHPDoc and cleanup workflow.
6+
7+
.. list-table::
8+
:header-rows: 1
9+
10+
* - Class
11+
- Enabled by default
12+
- Summary
13+
* - ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``
14+
- Yes
15+
- Infers ``@param``, ``@return``, and ``@throws`` tags.
16+
* - ``FastForward\DevTools\Rector\RemoveEmptyDocBlockRector``
17+
- Yes
18+
- Removes empty class and method docblocks.
19+
* - ``FastForward\DevTools\Rector\AddMissingClassPhpDocRector``
20+
- No
21+
- Generates a basic class docblock with an optional ``@package`` tag.
22+
23+
The packaged ``rector.php`` enables only
24+
``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector`` and
25+
``FastForward\DevTools\Rector\RemoveEmptyDocBlockRector``.
26+
``FastForward\DevTools\Rector\AddMissingClassPhpDocRector`` is available for
27+
explicit opt-in in projects that want it.

‎docs/configuration/index.rst‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
Configuration
22
=============
33

4-
FastForward DevTools is strictly built on the philosophy of **Convention over Configuration**. This section explains how configurations are supplied by default and how they can be modified.
5-
6-
By default, the plugin aims to provide zero-configuration setups for all underlying QA tools. However, identifying that advanced scenarios may require specific rulesets or paths, the architecture supports granular overrides locally within your project context.
7-
8-
In this Section
9-
---------------
4+
FastForward DevTools follows convention over configuration. Consumer projects
5+
start with useful packaged defaults, but local overrides always win when a
6+
command supports them.
107

118
.. toctree::
129
:maxdepth: 1
1310

11+
tooling-defaults
1412
overriding-defaults

0 commit comments

Comments
 (0)