Release version 1.0.0 #33
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add badges, installation instructions, a contributing section and license information to the Readme.
This adds a new external PHPCS standard called `PHPCSDev` for use by sniff developers to check the code style of their sniff repo code.
Often, sniff repos will use the code style of the standard they are adding. However, not all sniff repos are actually about code style.
So for those repos which need a basic standard which will still keep their code-base consistent, this standard should be useful.
The standard checks the following:
* Compliance with PSR-2.
* Use of camelCaps variable and function names.
* Use of normalized arrays.
* All files, classes, functions and properties are documented with a docblock and contain the minimally needed information.
* A small number of arbitrary additional code style checks.
* PHP cross-version compatibility, while allowing for the tokens back-filled by PHPCS itself.
**Note**: for optimal results, the project custom ruleset should set the `testVersion` config variable.
This is not done by default as config variables are currently difficult to overrule.
Refs:
- squizlabs/PHP_CodeSniffer#2197
- squizlabs/PHP_CodeSniffer#1821
The ruleset can be used like any other ruleset and specific sniffs and settings can be added to or overruled from a custom project based ruleset.
Includes adding QA checks for this ruleset to the Travis script.
This: * Adds a custom PHPCS ruleset which uses the `PHPCSDev` ruleset to check the code style of code in this repo. * Adds convenience scripts to the `composer.json` file to check the code of the repo. * And allows for individual developers to overload the `phpcs.xml.dist` file by ignoring the typical overload files.
New feature: PHPCSDev ruleset
This adds a custom script which will check whether each and every sniff is accompanied by a documentation XML file (warning) as well as unit test files (error).
The script will be available in the Composer `vendor/bin` directory as `phpcs-check-feature-completeness`.
Notes:
* To only show errors, the script can be run in `quiet` mode by passing the `-q` flag on the command line.
See the included documentation in the `README.md` file for other available options.
* The script has been set up in such a way that it can both be used by PHPCS itself, as well as by external standards which use the PHPCS native unit test suite.
To use the tool, run it from the root of the external standards repo like so:
`vendor/bin/phpcs-check-feature-completeness`
or when not installed via Composer:
`php -f "path/to/PHPCSDevTools/bin/phpcs-check-feature-completeness"`
* The list of sniffs to check completeness for is determined by getting a list of all files in `Sniffs` directories, where the files have a name ending with `Sniff.php` and not prefixed with `Abstract`.
* The "has tests" check verifies that a `UnitTest.php` file is present for each sniff in the standard's `Tests` directory and _at least_ one test case file.
* The "has docs" check verifies that a `Standard.xml` file is present for each sniff in the standard's `Docs` directory.
When implementing this check in CI, it only needs to be run on one build as the results won't change between PHP versions.
An earlier version of this script was originally pulled to PHPCS itself in PR 2364.
…omplete-script New feature: script to check that sniffs are "feature complete"
* Add simple `verbose` mode.
When enabled, the script will show which directories are searched for sniffs.
* Improve progress reporting.
- Limit progress reporting to 60 dots per line.
- Add `# / # ( #%) type status at the end of each line.
* Add credits line to the version information.
* Minor fix to help display.
This adds a new external PHPCS standard named `Debug` intended only for use by sniff developers.
This `Debug` standard will contain sniffs which can help sniff developers _during the development of new sniffs_.
Initially, this standard only contains one sniff: `Debug.Debug.TokenList`.
This sniff will display compact, but detailed information about the tokens found in a (test) file.
This sniff is compatible with PHPCS 3.0+.
Typical usage:
* Set up a test case file for a new sniff you intend to write.
* Run PHPCS over the test case file using this standard to see the tokens found listed:
`phpcs ./NewSniffNameUnitTest.inc --standard=Debug`
* Or use it together with the new sniff you are developing:
`phpcs ./NewSniffNameUnitTest.inc --standard=YourStandard,Debug --sniffs=YourStandard.Category.NewSniffName`
PHPCS itself can also display this information using the `-vv` or `-vvv` verbosity flags, however, when using those, you will receive a *lot* more information than just the token list and while useful for debugging PHPCS itself, the additional information is mostly just noise when developing a sniff.
Includes documentation.
Includes unit tests.
…ript-minor-tweaks Feature complete check: various improvements
This: * Adds convenience scripts to the `composer.json` file to check the feature completeness of sniffs in this repo. * And adds running of this script to the Travis build.
This:
* Adds a PHPUnit `phpunit.xml.dist` configuration file.
* Adds a `phpunit-bootstrap.php` file to load the necessary prerequisites for the unit testing.
The PHPCS unit test suite needs a `bootstrap` file as of PHPCS 3.1.0 which, as of then, also supports PHPUnit 6.x.
* Adds convenience scripts to the `composer.json` file to test the code of the repo.
* Adds the necessary changes to the Travis script to test against the relevant PHP / PHPCS combinations.
* And allows for individual developers to overload the `phpunit.xml.dist` file by ignoring the typical overload files.
New feature: Debug ruleset and sniff
Only align the "end of line" status when there is more than 1 line.
…ript-minor-tweaks Feature complete check: only pad end-of-line status when > 1 lines
PHPCS 3.5.0 will backfill the new PHP 7.4 `T_BAD_CHARACTER` token. Refs: * squizlabs/PHP_CodeSniffer@96f878f
…count-for-phpcs-350-backfill PHPCSDev: account for new PHPCS backfill
…ible ... to prevent conflicts with projects, be it external standards or end-user projects, which require the plugin themselves as well. Note: Version `0.4.0` is excluded from being installed due to a bug which made it far less usable. Ref: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
…sues-with-phpcs-plugin Composer: make the version requirement for the PHPCS plugin more flexible
* Add a "Header" to the output, giving some indication of what each column means. * Add padding to various parts of the line output so it all lines up. * Add minimal information about conditions to the output (condition count). Includes: * Updated unit tests to account for the changed output. * Updated sample output in the `Readme.md`. Also: * Fix incorrect PHPUnit `@covers` tags.
…utput Debug\TokenList: enhance the output
…more flexible, take two Further iteration on earlier fix, now no longer using unbound restraints. Note: Version `0.4.0` is excluded from being installed due to a [bug](PHPCSStandards/composer-installer#33) which made it far less usable. Ref: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
…-restraint Composer: make the version requirement for the Composer PHPCS plugin more flexible, take two
... as it is coming out in less than a month's time. ... and add a build against `nightly`, which _is_ allowed to fail. This build will - for now - only lint the PHP files and run the "feature complete" integration test. The unit tests are skipped for the time being, as the PHPCS native unit test suite is not yet compatible with PHP 8. Includes adjusting the Readme badge showing the versions the tool is tested against.
When using a project based install, this tool should normally be installed as a `--dev` tool. [skip-ci]
…allowed-to-fail Travis: PHP 7.4 is no longer allowed to fail
…-instructions Readme: fix installation instructions
As `var_dump()` isn't used in this sniff, no need to overload the Xdebug settings. This was a remnant of an earlier version of this code.
…bilize-test-lineendings Debug/TokenList: stabilize line endings in unit tests
…or-textual-fix CheckSniffCompleteness: minor textual update
…nge-namespace CheckSniffCompleteness: change namespace
…emove-namespace PHPCSDev ruleset: no need for the namespace
…namespace PHPCSDebug: change namespace / remove namespace prefix
This switches the basis of the `PHPCSDev` ruleset over to PSR12 with a few, selective exceptions: * Constant visibility will not be demanded as the minimum PHP requirement of PHPCS is PHP 5.4 and constant visibility did not become available until PHP 7.1. * The first condition of a multi-line control structure is allowed to be on the same line as the control structure keyword (PSR2 style). Includes updating the Readme to reflect this change. Includes removing some individual rule includes which are now already included via PSR12. **Note:** PSR12 enforces a blank line between each of the file header blocks. This rule can currently not (yet) be turned off in a modular way, i.e. for just one block. It is either on or off. This rule conflicts with the common practice of having no blank line between the PHP open tag and the file docblock. To turn this rule off, add `<exclude name="PSR12.Files.FileHeader.SpacingAfterBlock"/>` to the project specific ruleset, like is done in this PR for the PHPCSDevTools native project ruleset.
* The `env` variables do not need the `matrix` key.
* There is something weird going on with stages as the matrix wasn't expanding properly.
Hard-coding the stage name for each build in the `quicktest` stages at least works.
(and remove misplaced comment)
…-psr-12 PHPCSDev ruleset: switch over to PSR12 and other minor tweaks
... to document a class's changelog.
QA: use FQN when using global functions and constants
Travis: minor tweaks
…llow-more-since-tags PHPCSDev ruleset: allow for more than one `@since` tag
See the inline documentation of the ruleset for more information.
…dd-some-more-sniffs PHPCSDev ruleset: add a few select additional rules
* Ignore PHPUnit 8.x cache file. * Only run `composer validate` once per build. * Ignore the `.git` directory for Parallel Lint to make it faster.
Various small tweaks
The DealerDirect Composer plugin has just released version `0.6.0`. As Composer treats minors < 1.0 as majors, updating to this version requires an update to the `composer.json` requirements. > For pre-1.0 versions it also acts with safety in mind and treats `^0.3` as `>=0.3.0 <0.4.0`. Refs: * https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases/tag/v0.6.0 * https://getcomposer.org/doc/articles/versions.md#caret-version-range-
…pendency Composer: update PHPCS Composer plugin dependency
The `PHPCSDev` ruleset has a different PHPCS requirement from the other tooling in this repo, making it an awkward fit. With that in mind, the ruleset has been moved to a separate repository [`PHPCSDevCS`](https://github.com/PHPCSStandards/PHPCSDevCS). This now removes it from PHPCSDevtools. Includes: * Adding `PHPCSDevCS` as a `dev` dependency for this repo.
Remove the PHPCSDev ruleset
…e bootstrap ... which makes it independent of the dev environment of individual devs, making it more stable and less fiddly.
…onment Unit tests: set the `PHPCS_IGNORE_TESTS` environment variable from the bootstrap
Various minor tweaks
Add a changelog
|
Release tweet: https://twitter.com/jrf_nl/status/1227669711812468736 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Release checklist:
VERSIONfile.master(careful, GH defaults todevelop!) & copy & paste the changelog to itOpen PR to mergemasterintodevelopto get rid of the This branch is out-of-date with the base branch messages on each release. (only after major releases)