|
| 1 | +# Contributing to the PHP_CodeSniffer Documentation |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | + |
| 5 | +* [PHP_CodeSniffer Wiki](#php_codesniffer-wiki) |
| 6 | + * [How Does the Wiki Get Updated?](#how-does-the-wiki-get-updated) |
| 7 | + * [Contributing to the Wiki](#contributing-to-the-wiki) |
| 8 | + * [Guidelines for Updating the Wiki Files](#guidelines-for-updating-the-wiki-files) |
| 9 | + * [Running the pre-processing locally](#running-the-pre-processing-locally) |
| 10 | + * [Running Code Quality Checks Locally](#running-code-quality-checks-locally) |
| 11 | + * [Frequently Asked Questions](#frequently-asked-questions) |
| 12 | + * [Why Not Make the Wiki Publicly Editable?](#why-not-make-the-wiki-publicly-editable) |
| 13 | + |
| 14 | + |
| 15 | +## PHP_CodeSniffer Wiki |
| 16 | + |
| 17 | +For now, the documentation for the PHP_CodeSniffer project is available via the [project Wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki). |
| 18 | + |
| 19 | +### How Does the Wiki Get Updated? |
| 20 | + |
| 21 | +* The source of the Wiki was imported into this repository to maintain the commit history. |
| 22 | +* A [GitHub Actions workflow](https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation/blob/main/.github/workflows/publish-wiki.yml) was added: |
| 23 | + * It pre-processes the `.md` files to replace placeholders and inject some other content (see [Guidelines for Updating the Wiki Files](#guidelines-for-updating-the-wiki-files)). |
| 24 | + * And then it pushes the resulting updated `.md` files to the upstream Wiki repo. |
| 25 | + |
| 26 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
| 27 | + |
| 28 | + |
| 29 | +### Contributing to the Wiki |
| 30 | + |
| 31 | +If you would like to improve the documentation: |
| 32 | +1. Fork this repository. |
| 33 | +2. Create a new branch off the `main` branch. |
| 34 | +3. Make your changes. The Wiki source files are in the `/wiki` subdirectory. |
| 35 | +4. Commit your changes with a meaningful commit message. |
| 36 | +5. Push your changes to your fork. |
| 37 | +6. Submit a pull request from your fork to this repository. This process is documented in more detail in the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). |
| 38 | +7. Please ensure your pull requests passes all automated quality checks. |
| 39 | +8. If you updated anything which will be auto-replaced via the pre-processing: |
| 40 | + * The GitHub Actions workflow will do a "dry-run" for every PR (pre-process only, no push to the Wiki). |
| 41 | + * Please download the artifact which was created via this dry-run and verify the pre-processing replaced the output in the way you expected. |
| 42 | + |
| 43 | +When in doubt, open an issue first to discuss your change proposal. |
| 44 | + |
| 45 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
| 46 | + |
| 47 | + |
| 48 | +### Guidelines for Updating the Wiki Files |
| 49 | + |
| 50 | +* Small PRs fixing only one thing will be better received than larger PRs fixing a lot of things in one go. |
| 51 | +* Always use absolute links (https://...). 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. |
| 52 | +* Add table of contents placeholders if appropriate. |
| 53 | + The start of a page containing a table of contents should look like this: |
| 54 | + ```md |
| 55 | + ## Table of Contents |
| 56 | + |
| 57 | + <!-- START doctoc --> |
| 58 | + <!-- END doctoc --> |
| 59 | + |
| 60 | + *** |
| 61 | + |
| 62 | + ... the actual page ... |
| 63 | + ``` |
| 64 | +* Guidelines for command replacement placeholders: |
| 65 | + * A placeholder MUST look like `{{COMMAND-OUTPUT ...}}` with `...` replaced with a quoted `phpcs` or `phpcbf` command. Example: `{{COMMAND-OUTPUT "phpcbf --report-width=110 --no-colors -h"}}` |
| 66 | + * A placeholder MUST be at the start of a line. |
| 67 | + * A placeholder MUST be on a line by itself. |
| 68 | + * Commands will be run from the project root directory. Keep this in mind when adding a placeholder to a Wiki file. |
| 69 | +* The command replacement will not add markdown code fence syntax, so make sure to do this yourself. |
| 70 | +* If a code sample is needed to generate the desired output, place the code sample in a file in the `build/wiki-code-samples` directory. |
| 71 | + |
| 72 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
| 73 | + |
| 74 | + |
| 75 | +#### Running the pre-processing locally |
| 76 | + |
| 77 | +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. |
| 78 | +However, if you are making extensive changes, you may still want to test things locally before submitting your PR. |
| 79 | + |
| 80 | +> [!IMPORTANT] |
| 81 | +> Run the bash script first, only run the TOC replacement after. |
| 82 | + |
| 83 | +The bash script used for the command replacements can be run locally from the project root directory by invoking: |
| 84 | + |
| 85 | +```bash |
| 86 | +build/wiki-command-replacer.sh |
| 87 | +``` |
| 88 | + |
| 89 | +Notes: |
| 90 | +* For the bash script to succeed, the `phpcs` and `phpcbf` commands need to be available in the `PATH` for your OS. |
| 91 | +* The bash script will copy the Wiki files to the `_wiki` directory before making any replacements to prevent anyone accidentally committing the processed files. |
| 92 | + |
| 93 | +The table of contents generation can be tested locally by installing the `doctoc` tool and running this locally like so: |
| 94 | + |
| 95 | +```bash |
| 96 | +npm install -g doctoc |
| 97 | +doctoc ./_wiki/ --github --maxlevel 4 --update-only |
| 98 | +doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only |
| 99 | +``` |
| 100 | + |
| 101 | +Note that this presumes the command replacer has already run and the files have already been copied to the `_wiki` directory. |
| 102 | + |
| 103 | +If you only want to test the TOC generation, make sure you copy the Wiki files to the `_wiki` directory before running these commands. |
| 104 | + |
| 105 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
| 106 | + |
| 107 | + |
| 108 | +#### Running Code Quality Checks Locally |
| 109 | + |
| 110 | +All used code quality checks can be run locally. |
| 111 | +Configuration files have been committed to the repository to ensure you will locally get the same results as when the tooling runs in CI. |
| 112 | + |
| 113 | +To run the quality checks locally, install the following tooling: |
| 114 | +* [Yamllint](https://github.com/adrienverge/yamllint) |
| 115 | + * [Installation instructions](https://yamllint.readthedocs.io/en/stable/quickstart.html) |
| 116 | + * Run it like so: `yamllint . --format colored --strict --list-files` |
| 117 | +* [Actionlint](https://github.com/rhysd/actionlint) |
| 118 | + * [Installation instructions](https://github.com/rhysd/actionlint/blob/main/docs/install.md) |
| 119 | + * Run it like so: `actionlint -verbose` |
| 120 | +* [Markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) |
| 121 | + * [Installation instructions](https://github.com/DavidAnson/markdownlint-cli2#install) |
| 122 | + * Run it like so: `markdownlint-cli2` |
| 123 | +* [Lychee](https://github.com/lycheeverse/lychee) |
| 124 | + * [Installation instructions](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation) |
| 125 | + * Run it like so: `lychee "./**/*.md"` |
| 126 | + Note: this command will show "false positives" locally for the `_Sidebar.md` file. These can be ignored. |
| 127 | +* [CSpell](https://cspell.org/) |
| 128 | + * [Installation instructions](https://cspell.org/docs/installation) |
| 129 | + * Run it like so: `cspell "**/*.md"` |
| 130 | +* [Shellcheck](https://www.shellcheck.net/) |
| 131 | + * [Installation instructions](https://github.com/koalaman/shellcheck?tab=readme-ov-file#installing) |
| 132 | + * Run it like so: `shellcheck ./build/wiki-command-replacer.sh` |
| 133 | + |
| 134 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
| 135 | + |
| 136 | + |
| 137 | +### Frequently Asked Questions |
| 138 | + |
| 139 | +#### Why Not Make the Wiki Publicly Editable? |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +As a secondary reason, there are parts of the Wiki (especially the output examples), which were pretty out of date. |
| 144 | +By having the Wiki source in this repository, it allows for automating certain updates which would otherwise have to be done manually. |
| 145 | + |
| 146 | +<p align="right"><a href="#table-of-contents">back to top</a></p> |
0 commit comments