|
| 1 | +# Contributing to the PHP_CodeSniffer documentation |
| 2 | + |
| 3 | +## PHP_CodeSniffer Wiki |
| 4 | + |
| 5 | +For now, the documentation for the PHP_CodeSniffer project is available via the [project Wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki). |
| 6 | + |
| 7 | +### How does the wiki get updated ? |
| 8 | + |
| 9 | +* The source of the Wiki was imported into this repository to maintain the commit history. |
| 10 | +* A [GitHub Actions workflow](https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation/blob/main/.github/workflows/publish-wiki.yml) was added to automatically push changes made in the Wiki files in this repository to the upstream Wiki repo. |
| 11 | +* Prior to pushing the changes, the workflow will pre-process the files and make the following changes: |
| 12 | + * Replace `{{COMMAND-OUTPUT ...}}` command-line output placeholders with actual command-line output from either `phpcs` or `phpcbf`. |
| 13 | + The code samples used for generating some of this output can be found in the `build/wiki/code-samples` directory. |
| 14 | + * Replace `<!-- START doctoc --> <!-- END doctoc -->` placeholders with a Table of Contents for the page in Markdown. |
| 15 | + |
| 16 | + |
| 17 | +### Contributing to the Wiki |
| 18 | + |
| 19 | +If you would like to improve the documentation: |
| 20 | +1. Fork this repository. |
| 21 | +2. Create a new branch off the `main` branch. |
| 22 | +3. Make your changes. The Wiki source files are in the `/wiki` subdirectory. |
| 23 | +4. Commit your changes with a meaningful commit message. |
| 24 | +5. Push your changes to your fork. |
| 25 | +6. Submit a pull request from your fork to this repository. |
| 26 | +7. Please ensure your pull requests passes all automated quality checks. |
| 27 | +8. If you updated anything which will be auto-replaced via the preprocessing: |
| 28 | + * The GitHub Actions workflow will do a "dry-run" for every PR (pre-process only, no push to the wiki). |
| 29 | + * Please download the artifact which was created via this dry-run and verify the preprocessing replaced the output in the way you expected. |
| 30 | + |
| 31 | +When in doubt, open an issue first to discuss your change proposal. |
| 32 | + |
| 33 | + |
| 34 | +### Guidelines for updating the wiki files |
| 35 | + |
| 36 | +* Small PRs fixing only one thing will be better received than larger PRs fixing a lot of things in one go. |
| 37 | +* Always use fully qualified links. This ensures that the links will work when pages are viewed/edited in this repo, as well as when the pages are viewed from the PHPCS wiki. |
| 38 | +* Add table of contents markers if appropriate. |
| 39 | + The start of a page containing a table of contents should look like this: |
| 40 | + ```md |
| 41 | + ## Table of contents |
| 42 | + |
| 43 | + <!-- START doctoc --> |
| 44 | + <!-- END doctoc --> |
| 45 | + |
| 46 | + *** |
| 47 | + |
| 48 | + ... the actual page ... |
| 49 | + ``` |
| 50 | +* Regarding command replacement markers ... |
| 51 | + * A marker MUST look like `{{COMMAND-OUTPUT ...}}` with `...` being replacement with a quoted `phpcs` or `phpcbf` command. |
| 52 | + * A marker MUST be at the start of a line. |
| 53 | + * A marker MUST be on a line by itself. |
| 54 | +* The command replacement will not add markdown code fence syntax, so make sure to do this yourself. |
| 55 | + |
| 56 | + |
| 57 | +#### Running the pre-processing locally |
| 58 | + |
| 59 | +As noted above, you don't _need_ to run the pre-processing locally, a dry-run will be done via GitHub Actions for each PR. |
| 60 | +However, if you are making extensive changes, you may still want to test things locally before submitting your PR. |
| 61 | + |
| 62 | +> [!IMPORTANT] |
| 63 | +> Run the bash script first, only run the TOC replacement after. |
| 64 | + |
| 65 | +The bash script used for the command replacements can be run locally by invoking: |
| 66 | + |
| 67 | +```bash |
| 68 | +build/wiki-command-replacer.sh |
| 69 | +``` |
| 70 | + |
| 71 | +Notes: |
| 72 | +* For the bash script to succeed, the `phpcs` and `phpcbf` commands need to be available in the `PATH` for your OS. |
| 73 | +* The bash script will copy the wiki files to the `_wiki` directory before making any replacements to prevent anyone accidentally committing the processed files. |
| 74 | + |
| 75 | +The table of contents generation can be tested locally by installing the `doctoc` tool and running this locally like so: |
| 76 | + |
| 77 | +```bash |
| 78 | +npm install -g doctoc |
| 79 | +doctoc ./_wiki/ --github --maxlevel 4 --update-only |
| 80 | +doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only |
| 81 | +``` |
| 82 | + |
| 83 | +Note that this presumes the command replacer has already run and the files have already been copied to the `_wiki` directory. |
| 84 | + |
| 85 | +If you only want to test the TOC generation, make sure you copy the wiki files to the `_wiki` directory before running these commands. |
| 86 | + |
| 87 | + |
| 88 | +#### Running code quality checks locally |
| 89 | + |
| 90 | +All used code quality checks can be run locally. |
| 91 | +Configuration files have been committed to the repository to ensure you will locally get the same results as when the tooling runs in CI. |
| 92 | + |
| 93 | +To run the quality checks locally, install the following tooling: |
| 94 | +* [Yamllint](https://github.com/adrienverge/yamllint) |
| 95 | + * [Installation instructions](https://yamllint.readthedocs.io/en/stable/quickstart.html) |
| 96 | + * Run it like so: `yamllint . --format colored --strict --list-files` |
| 97 | +* [Actionlint](https://github.com/rhysd/actionlint) |
| 98 | + * [Installation instructions](https://github.com/rhysd/actionlint/blob/main/docs/install.md) |
| 99 | + * Run it like so: `actionlint -verbose` |
| 100 | +* [Markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) |
| 101 | + * [Installation instructions](https://github.com/DavidAnson/markdownlint-cli2#install) |
| 102 | + * Run it like so: `markdownlint-cli2` |
| 103 | +* [Lychee](https://github.com/lycheeverse/lychee) |
| 104 | + * [Installation instructions](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation) |
| 105 | + * Run it like so: `lychee "./**/*.md"` |
| 106 | + Note: this command will show "false positives" locally for the `_Sidebar.md` file. These can be ignored. |
| 107 | +* [CSpell](https://cspell.org/) |
| 108 | + * [Installation instructions](https://cspell.org/docs/installation) |
| 109 | + * Run it like so: `cspell "**/*.md"` |
| 110 | +* [Shellcheck](https://www.shellcheck.net/) |
| 111 | + * [Installation instructions](https://github.com/koalaman/shellcheck?tab=readme-ov-file#installing) |
| 112 | + * Run it like so: `shellcheck ./build/wiki-command-replacer.sh` |
| 113 | + |
| 114 | + |
| 115 | +### Frequently Asked Questions |
| 116 | + |
| 117 | +#### Why not make the Wiki publicly editable ? |
| 118 | + |
| 119 | +Publicly editable Wiki pages for big projects get vandalized pretty often and we don't want to risk this type of vandalism leading to users getting incorrect information. |
| 120 | + |
| 121 | +As a secondary reason, there are parts of the wiki (especially the output examples), which were pretty out of date. |
| 122 | +By having the wiki source in this repository, it allows for automating certain updates which would otherwise have to be done manually. |
0 commit comments