diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..da94022 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,78 @@ +--- +name: "\U0001F41B Bug report for sniffs" +about: I got unexpected behavior and think it is a bug. +title: '' + +--- + + + +## Bug Description + + + +## Given the following reproduction Scenario + + +The issue happens when running this command: + +```bash +phpcs -ps file.php --standard=... +``` + +... over a file containing this code: +```php +// Place your code sample here. +``` + + +... with this custom ruleset: +```xml + + + ... + +``` + + +### I'd expect the following behaviour + + + +### Instead this happened + + + +## Environment + + +| Environment | Answer | +| ----------------------- | ------------------------------------------------------------------------------ | +| PHP version | x.y.z | +| PHP_CodeSniffer version | x.y.z | +| PHPCSExtra version | x.y.z | +| PHPCSUtils version | x.y.z | +| Install type | e.g. Composer global, Composer project local, git clone, other (please expand) | + + +## Additional Context (optional) + + + +## Tested Against `develop` branch? + +- [ ] I have verified the issue still exists in the `develop` branch of PHPCSExtra. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..c6a0522 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,22 @@ +--- +name: "\U0001F680 Feature request" +about: I have a suggestion (and may want to implement it). +title: '' + +--- + +## Is your feature request related to a problem? + + +## Describe the solution you'd like + + +## Additional context (optional) + + +- [ ] I intend to create a pull request to implement this feature. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f36d0ed --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ + + +# Description + + + +## Related issues/external references + +Fixes # + + +## PR checklist + +- [ ] I have checked there is no other PR open for the same change. +- [ ] I have read the [Contribution Guidelines](https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation/blob/main/CONTRIBUTING.md). +- [ ] I grant the project the right to include my changes under the BSD-3-Clause license (and I have the right to grant these rights). +- [ ] I have verified that the code complies with the projects coding standards. +- [ ] [When adding a new Wiki page] I have added the new page to the `_Sidebar.md` file. + + diff --git a/.github/workflows/basic-qa.yml b/.github/workflows/basic-qa.yml index 1fafbe8..b840ff0 100644 --- a/.github/workflows/basic-qa.yml +++ b/.github/workflows/basic-qa.yml @@ -18,6 +18,10 @@ jobs: name: 'Lint Markdown' uses: PHPCSStandards/.github/.github/workflows/reusable-markdownlint.yml@main + remark: + name: 'QA Markdown' + uses: PHPCSStandards/.github/.github/workflows/reusable-remark.yml@main + yamllint: name: 'Lint Yaml' uses: PHPCSStandards/.github/.github/workflows/reusable-yamllint.yml@main @@ -77,3 +81,16 @@ jobs: # yamllint disable-line rule:line-length if: ${{ steps.spellcheck.outputs.success == false && steps.spellcheck.outputs.number_of_issues != 11 && steps.spellcheck.outputs.number_of_files_with_issues != 5}} run: exit 1 + + spellcheck-5: + name: Spellcheck-5 + # Config file: _typos.toml + + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: "Search for misspellings" + uses: "crate-ci/typos@v1" diff --git a/.github/workflows/deploy-to-wiki.yml b/.github/workflows/deploy-to-wiki.yml new file mode 100644 index 0000000..a5ab62b --- /dev/null +++ b/.github/workflows/deploy-to-wiki.yml @@ -0,0 +1,15 @@ + + +Automatically add the following at the top of each file: + +``` + +``` + + +Automatically replace output example placeholders with real output + diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml index b15ee47..ef9df2e 100644 --- a/.github/workflows/publish-wiki.yml +++ b/.github/workflows/publish-wiki.yml @@ -104,6 +104,8 @@ jobs: - name: Re-run tables of contents with different settings for specific file run: doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only + # TODO: + # Update output examples # ############################ # Deploy. diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 0000000..0ee28ea --- /dev/null +++ b/.remarkignore @@ -0,0 +1,5 @@ +# Ignore rules for Remark. +# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md + +/build/ +/node_modules/ diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 0000000..95c4c32 --- /dev/null +++ b/.remarkrc @@ -0,0 +1,36 @@ +{ + "plugins": [ + "remark-gfm", + ["remark-lint-checkbox-character-style", "consistent"], + ["remark-lint-checkbox-content-indent", "consistent"], + "remark-lint-definition-spacing", + "remark-lint-file-extension", + ["remark-lint-linebreak-style", "unix"], + ["remark-lint-link-title-style", "\""], + ["remark-lint-ordered-list-marker-style", "."], + "remark-lint-no-dead-urls", + "remark-lint-no-duplicate-defined-urls", + "remark-lint-no-duplicate-definitions", + "remark-lint-no-empty-url", + "remark-lint-no-file-name-consecutive-dashes", + "remark-lint-no-file-name-irregular-characters", + "remark-lint-no-file-name-outer-dashes", + "remark-lint-no-heading-like-paragraph", + "remark-lint-no-literal-urls", + "remark-lint-no-reference-like-url", + "remark-lint-no-shortcut-reference-image", + "remark-lint-no-table-indentation", + "remark-lint-no-undefined-references", + "remark-lint-no-unneeded-full-reference-image", + "remark-lint-no-unneeded-full-reference-link", + "remark-lint-no-unused-definitions", + ["remark-lint-strikethrough-marker", "~~"], + ["remark-lint-table-cell-padding", "consistent"], + "remark-lint-heading-whitespace", + "remark-lint-list-item-punctuation", + "remark-lint-match-punctuation", + "remark-lint-no-hr-after-heading", + "remark-lint-are-links-valid-duplicate", + "remark-validate-links" + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..632aa5d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,40 @@ +# Contributing to the PHP_CodeSniffer documentation + +## PHP_CodeSniffer Wiki + +For now, the documentation for the PHP_CodeSniffer project is available via the [project Wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki). + +### Contributing to the Wiki + +If you would like to improve the documentation: +1. Fork this repo. +2. Create a new branch off the `main` branch. +3. Make your changes. The Wiki source files are in the `/wiki` subdirectory. +4. Commit your changes with a meaningful commit message. +5. Push your changes to your fork. +6. Submit a pull request from your fork to this repository. + +When in doubt, open an issue first to discuss your change proposal. + +### How does the wiki get updated ? + +* The source of the Wiki was imported into this repository to maintain the commit history. +* 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 to the upstream Wiki repo. +* Prior to pushing the changes, the workflow will make various changes to the files: + * Replace ` ` placeholders with a Table of Contents for the page in Markdown. + * Replace `{{ .... }}` CLI output placeholders with actual CLI output. + The code samples used for this can be found in the `build/wiki/code-samples` directory. + +### Guidelines + +* 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. + + +### Frequently Asked Questions + +#### Why not make the Wiki publicly editable ? + +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. + +As a secondary reason, there are parts of the wiki (especially the output examples) which were pretty out of date. +By having the wiki source in this repo, it allows for automating certain updates which would otherwise have to be done manually. diff --git a/README.md b/README.md index 174bbda..38f9f65 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,8 @@ The intention is for that website to be a GitHub Pages/Jekyll site, but we'll ne In the mean time, the documentation for the PHP_CodeSniffer project is available via the [project Wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki) and made publicly editable via this repository. _This is an interim solution and the intention is to eventually migrate the wiki documentation to the website._ + + +## Want to contribute ? + +Have a look at the [CONTRIBUTING guide](CONTRIBUTING.md). diff --git a/_typos.toml b/_typos.toml new file mode 100644 index 0000000..b94013d --- /dev/null +++ b/_typos.toml @@ -0,0 +1,15 @@ +[files] +extend-exclude = [ + ".git/", +] +ignore-hidden = true + +[default] +locale = "en-gb" +check-filename = true + +[default.extend-words] +# Don't correct for the CLI flag name. +colors = "colors" +# Don't correct for the Zend tooling name. +Analyzer = "Analyzer"