Wiki/User Upgrade Guide: add some extra links
536b44f
Wiki/Reporting: update example output for `gitblame` reports
The generation of the output examples for the `gitblame` report cannot easily be automated for the following reasons:
1. If using code samples committed to this repo, there would (for now) only be one author, making the output example not a very good example.
2. If generating these output examples from an existing codebase, there may be privacy issues in play when using the handles/names of real developers.
All in all, for now, the output has been manually updated to use the current report format, but using fake data.
e8d1ca1
Wiki/Tutorial: update example output for the sniff
6e509c0
Wiki/Fixing-errors: update example output from `phpcbf`
972c6d3
GH Actions: add automation for generating output examples for the wiki (#20)
* GH Actions: prepare the workflow for auto-generating output snippets
* Run phpcs/phpcbf commands to auto-generate output blocks
* GH Actions/basic QA: add shellcheck job
As this repo now contains a shell script to find & replace placeholders for output snippets in the wiki files with real output, let's also run a minimal QA check on the code of the shell script.
Refs:
* https://github.com/koalaman/shellcheck
* https://github.com/koalaman/shellcheck/wiki
---------
Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>
Co-authored-by: Dan Wallis <dan@wallis.nz>
00e017c
Wiki: improve readability for the 4.0 upgrade guides
The GitHub wiki markdown parser does not handle new lines in the same way as the markdown parser used, for instance, for GitHub issues.
The net effect of this, is that when there is a blank line between two sentences, the sentences will be formatted as separate paragraphs, but if there is only a new line between two sentences, they will be joined together into one long paragraph.
So using a new line will not enforce a "soft break" (`<br/>`) within a paragraph.
To get a "soft break" with the GH wiki markdown parser, you need two trailing spaces at the end of a sentence.
The trouble with that, is, of course, that a lot of editors will automatically try to remove these kind of trailing spaces, but so be it. Just means reviewers need to be extra careful about this.
e6ef29b
Wiki: always have filenames in backticks
Hoping I've caught them all, but not claiming completeness.
7f83b1c
Wiki/Reporting: improve report display
3853b05
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.
081cc1b
Wiki/Usage: update paths in commands
The `CodeSniffer` directory is a directory from way back in PHPCS 2.0 and is not really relevant to these output examples anyway, so let's use more generic names.
f11cde5
Wiki: various grammar and spelling fixes
831c37a
Wiki: fix broken links to Rhino
12c3069
Wiki: always use fully qualified links
76e3d69
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
244d2f1
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
3c103ad
4.0 dev upgrade guide: add note about changed format of `Common::$allowedTypes`
Fixes PHPCSStandards/PHP_CodeSniffer 1143
jrfnl
committed
Jun 21, 2025
25d72e0
4.0 | Version-4.0-User-Upgrade-Guide: add mention of another renamed error code
Ref: PHPCSStandards/PHP_CodeSniffer 1136
jrfnl
committed
Jun 17, 2025
1a675b0
4.0 dev upgrade guide: fix formatting issue
Looks like the call out blocks don't work within a list.
jrfnl
committed
May 27, 2025
f2fe8f6
4.0 dev upgrade guide: fix tabs vs spaces
jrfnl
committed
May 27, 2025
588dbe8
4.0 | User upgrade guide: add information about (upcoming) branch rename and impact
jrfnl
committed
May 19, 2025
b1a810a
Update schema URL in example code
jrfnl
committed
May 19, 2025
564e50d
4.0 | Document the new (and old) exit codes and the `ignore_non_auto_fixable_on_exit` flag
jrfnl
committed
May 13, 2025
195ace0
4.0-beta | Add upgrade guides for upgrading to PHPCS 4.0
jrfnl
committed
May 13, 2025
d308963
About Standards: add section about how PHPCS determines the standard to use
jrfnl
committed
May 9, 2025
958fda5
Fixing errors/Reporting: move Diff report info
The information about the `Diff` report was included in the "Fixing errors automatically" page, but is kind of dated as the `phpcbf` script has by now existed for a fair number of years.
This changes the "Fixing errors" page to focus on the `phpcbf` tool and moves the information about the "Diff" report to the "Reporting" page.
jrfnl
committed
May 9, 2025
5f49129
Configuration Options: improve readability and clarity
jrfnl
committed
May 9, 2025
599fd6e
Usage, Advanced Usage: improve readability and clarity
jrfnl
committed
May 9, 2025
dd7aef3
Home: improve readability and clarity
jrfnl
committed
May 9, 2025
6815b23
Remove ablist language and other textual improvements
jrfnl
committed
May 8, 2025
872edc1
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
20d98dc