Advanced Usage: fix broken link
4.0 | Wiki: updates for change of the default standard from PEAR to PSR12
Includes automating various output example blocks via the automated replacement mechanism.
:warning: This commit should only be merged AFTER the PHPCS 4.0 release! The code samples used for the auto-generated output are specifically crafted to give errors/warnings against PSR12, not against the PEAR standard. :warning:
Note: this also means that the artifact containing the preprocessed output will need to be regenerated after the PHPCS 4.0 release to get an accurate representation of the updated wiki pages.
Where auto-generated output blocks was not an option, like when the output block in the documentation only displays part of a larger output stream, the command used to manually update the existing output block has been added as an inline comment.
Regarding the "diff" report - even with manually installing DiffUtils in GH Actions, the report does not display, so unless someone figures out why, this will need to be manually updated.
As for the "info" report, while this could be auto-generated using something like `{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=info --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileB.php build/wiki-code-samples/path/to/code/fileC.php"}}`, I believe the existing report example demonstrates the usecase for this report better, so I have deliberately not updated it.
Also not that for the "interactive" reporting code sample, I'm cheating a bit as interactive mode obviously cannot be auto-generated without user interaction, but we do know what the report should look like ;-)
4.0 | Wiki: update for removal of CSS/JS support in sniffs
4.0 | Wiki/Advanced Usage: update for change in PHP open tag tokenization
Notes:
1. I've toned down the indentation a little to reduce the need for vertical scrolling.
This is in line with how these output samples were previously presented in the wiki.
2. And while I _am_ adding a `annotated-ruleset/debug-output.php` file which can be used to generate these output samples to the `build/wiki-code-samples` directory, at this time, we cannot yet selectively only retrieve the desired output for this documentation, so we cannot automate updating these output blocks.
This will hopefully change in the foreseeable future once PHPCSStandards/PHP_CodeSniffer 1030 has been implemented, though as there is also a textual part which refers to line numbers in the output blocks, manually updating these output blocks may still be the more stable way.
For the "Verbose Token Processing Output" I've added a comment to document how to retrieve the desired output to update this output block.
I've used the `PEAR` standard, not the `PSR12` standard to keep the output within reasonable bounds.
4.0 | Wiki/Advanced Usage: update information about deprecated/removed ignore annotations
4.0 | Wiki/Advanced-Usage: add the cumulative exit codes (#51)
- Added a table with the cumulative exit codes as documented in the interim proposal (https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/184#issuecomment-2644329771).
This ensures a complete exit code documentation where users and devs can easily read exactly what the cumulative exit codes are.
- Also added another description to the `0` exit code to describe when issues are fixed with no issues remaining, because "clean code base" could just be interpreted as no issues at all.
Wiki/Advanced-Usage: update example output from `--config-show`
As the PHPCS installation used in GH Actions won't have a `CodeSniffer.conf` file yet, this cannot be automated.
Aside from that, automating this would yield inconsistent results when contributors would run the command output replacement script locally.
Replacing it now with a manually crafted, updated output example.
Wiki: various grammar and spelling fixes
Wiki: always use fully qualified links
GH Actions/publish-wiki: auto-generate table of contents (#6)
This commit adds steps to the workflow to auto-generate a GitHub wiki compatible table of contents in most wiki pages.
This reduces the risk of a TOC being out-of-date or containing incorrectly formatted links, as well as reduces the maintenance burden.
This action uses the `doctoc` pages to generate the table of contents and this can be tested locally using the same steps as used in the GH Actions workflow:
```
npm install -g doctoc
cp -v -a wiki _wiki
doctoc ./_wiki/ --github --maxlevel 4 --update-only
doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only
```
Notes:
* The files are copied to a `_wiki` directory - which is `.gitignore`d - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.
* The `--github` flag puts the TOC generation in GitHub compatible mode.
* The `--update-only` flag means that only markdown files containing the `<!-- START doctoc -->` and `<!-- END doctoc -->` markers will be updated and files without those markers will be left alone.
* By default, the TOC will contain all headers up to the indicated `--maxlevel`.
For the V 4.0 Dev upgrade guide, this looked weird, what with some "Upgrading" headers being at level 4 and some at level 5.
To mitigate this, a couple of headers have been turned into "bold phrases" instead.
Along the same lines, for the V 4.0 User upgrade guide, the level 4 headers were always "Upgrading". Those belong with their parent heading and IMO do not need to be separately called out in the TOC, which explains the second call to `doctoc` to overrule the TOC for that file specifically with a `--maxlevel 3` setting.
* The start/end markers have been added to all files which contained a TOC, except for one: `Reporting.md`.
The reason for this exception is that the section order in the file does not match the current TOC order, with the existing TOC order making sense from a TOC point of view, while the section order makes sense from a "types of reports most used" point of view.
Whether this page should be re-organized or not, is outside the scope of this PR.
To allow contributors to review the resulting pre-processed wiki files, the files are uploaded as an artifact when a PR dry-run is being executed and a comment is posted on the PR requesting the contributor to review the pre-processed files.
Includes adding a TOC to the Coding Standards Tutorial page and adding "back to top" links within the page.
Ref:
* https://github.com/thlorenz/doctoc
GH Actions: add a workflow to automatically deploy the wiki
This commit introduces a workflow, which will:
* Automatically deploy the wiki files to the [PHP_CodeSniffer repo wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki) on every push to the `main` branch.
* Will do a dry-run, without actually deploying, whenever a PR is created which would update the wiki files.
This way, the wiki is opened up to contributions via pull requests and is no longer limited to only edits made by committers.
A prominent warning is automatically added as a (hidden) comment at the top of each wiki file to warn committers not to edit the wiki file in the GitHub wiki interface.
Any edits made via the GitHub wiki interface or by directly pushing to the wiki repository, will be lost and overwritten via this workflow the next time a change is pushed to the `main` branch of this repo.
This commit also adds a `_Footer.md` file, which will automatically be displayed at the bottom of each wiki page to point out that the wiki is editable via PRs to this repo.
Notes:
* The files are copied to a `_wiki` directory - which is `.gitignore`d - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.
* Commits for "push" events to the `main` branch will get the same commit message for the wiki as the _last_ commit on the `main` branch.
For that reason, merge commits are not allowed in this repo and PRs with only one commit are strongly preferred.
* Dry-run commits for PR events and commits triggered by other events, will get a simplified message referencing the sha of the last commit.
* If the net effect of a commit results in no changes to the wiki files (CI changes and such), no commit will be made to the wiki.
* The workflow is set up to fail if GitHub has an outage for git operations.
That should protect the wiki from going down by a broken/partial commit and allows for retriggering a deploy once the outage has passed by re-running the failed build.
Future scope (upcoming):
* Automate generation of the Table of Contents for wiki pages.
* Automate re-generation of output examples used in the wiki pages.
Refs:
* https://github.com/Andrew-Chen-Wang/github-wiki-action
* https://github.com/crazy-max/ghaction-github-status
4.0 | Document the new (and old) exit codes and the `ignore_non_auto_fixable_on_exit` flag
jrfnl
committed
May 13, 2025
Usage, Advanced Usage: improve readability and clarity
jrfnl
committed
May 9, 2025
Update/add table of contents for various pages
Generated table of contents using https://bitdowntoc.derlin.ch/
Includes adding additional "back to top" links.
jrfnl
committed
May 8, 2025
CS/markdownlint: various whitespace fixes
jrfnl
committed
May 8, 2025
CS/markdownlint: consistent list item indentation
jrfnl
committed
May 8, 2025
CS/markdownlint: use fenced codeblocks everywhere
This makes it easier to copy/paste updated output to the wiki docs.
jrfnl
committed
May 8, 2025
Update sniff code vs error code + additional info about this in Reporting and Advanced Usage
Refs: #319, #328
Co-authored-by: Joachim Noreiko <[email protected] >
jrfnl
committed
Feb 6, 2024
Remove reference to PEAR package
Not that it's being used for _this_ package, but PEAR packages are much less common nowadays, so the reference looks dated.
jrfnl
committed
Nov 12, 2023
Add "back to top" links under each section
... on long pages which contain a table of contents.
jrfnl
committed
Nov 12, 2023
Use highlighted blocks for important information
Ref: https://github.com/orgs/community/discussions/16925
jrfnl
committed
Nov 12, 2023
Update URLs to point to the PHPCSStandards repo
jrfnl
committed
Nov 12, 2023
Fixed language around phpcs:ignore annotation (issues #3657)
Updated Advanced Usage (markdown)
Updated Advanced Usage (markdown)
Updated Advanced Usage (markdown)
Add docs for comment syntax notes
Documented selective disable/enable using the new comment syntax