Merge remote-tracking branch 'upstream/master' into feature/fixer-con…

…flict/PSR12/Squiz.Functions.FunctionDeclarationArgumentSpacing
PHPCSStandards · Jan 7, 2025 · 7d44d55 · 7d44d55
2 parents a32b788 + b43e1d8
commit 7d44d55
Show file tree

Hide file tree

Showing 519 changed files with 16,369 additions and 1,446 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -339,6 +339,43 @@ Example:
 for
 ```
 
+#### Tests covering code which has OS-specific behaviour
+
+Most code in PHP_CodeSniffer is operating system agnostic.
+However, there are a few places which include OS-specific conditions, most notably for Windows.
+
+Tests which cover code which have Windows specific conditions should be marked with a `@group Windows` annotation to allow for running those tests separately/selectively in CI.
+
+#### Tests covering code which has CS/CBF specific behaviour
+
+There are a few places in PHPCS where code uses a global `PHP_CODESNIFFER_CBF` constant to determine what to do.
+This makes testing this code more complicated.
+
+Tests which will only work correctly when `PHP_CODESNIFFER_CBF === false` should get the following test skip condition at the top of the test method:
+```php
+if (PHP_CODESNIFFER_CBF === true) {
+    $this->markTestSkipped('This test needs CS mode to run');
+}
+```
+
+Tests which are specifically intended to cover code run when `PHP_CODESNIFFER_CBF === true` should:
+1. Be annotated with `@group CBF`.
+2. Have a test skip condition at the top of the test method like so:
+    ```php
+    if (PHP_CODESNIFFER_CBF === false) {
+        $this->markTestSkipped('This test needs CBF mode to run');
+    }
+    ```
+
+By default, the tests are run with the `PHP_CODESNIFFER_CBF` constant set to `false` and tests in the `@group CBF` will not be run.
+
+To run the tests specific to the use of `PHP_CODESNIFFER_CBF === true`:
+1. Set `<php><env name="PHP_CODESNIFFER_CBF" value="1"/></php>` in a `phpunit.xml` file or set the ENV variable on an OS-level.
+2. Run the tests like so:
+    ```bash
+    vendor/bin/phpunit --group CBF --exclude-group nothing
+    ```
+
 
 ### Submitting Your Pull Request
 

diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -21,6 +21,10 @@ labels:
     draft: false
     files:
       - "src/Fixer.php$"
+  - label: "Core Component: Generators"
+    draft: false
+    files:
+      - "src/Generators/.*"
   - label: "Core Component: Reports"
     draft: false
     files:
@@ -90,7 +94,7 @@ labels:
   - label: "Type: documentation"
     draft: false
     files:
-      - '/Docs/[A-Za-z0-9-]*/.*Standard.xml$'
+      - 'src/Standards/.*/Docs/[A-Za-z0-9-]*/.*Standard.xml$'
   - label: "Type: documentation"
     draft: false
     files:

diff --git a/.github/release-checklist.md b/.github/release-checklist.md
@@ -0,0 +1,126 @@
+# Release checklist
+
+## Before Release
+
+### General
+
+- [ ] Verify, and if necessary, update the version constraints for dependencies in the `composer.json` - PR #xxx
+- [ ] Verify that any new functions have type declarations (ClassName/array/callable) whenever possible.
+- [ ] Verify that the license tags all refer to the _new_ organisation and no longer to Squizlabs. (easily overlooked in new files)
+- [ ] Verify that `@copyright` tags in new files use `@copyright 20xx PHPCSStandards and contributors`.
+
+### Wiki
+
+- [ ] Fetch changes and check against vandalism.
+- [ ] Verify that any new `public` properties are listed on the Customizable Properties page in the Wiki.
+- [ ] Verify that any new sniffs which have `public` properties are listed on the Customizable Properties page in the Wiki.
+- [ ] Verify that any new CLI options are listed in the Wiki.
+- [ ] Verify that any new Reports have a section in the Reports page in the Wiki.
+
+### Majors only
+
+- [ ] Move old changelog entries to `CHANGELOG_OLD.md` file.
+- [ ] Verify that everything deprecated during the previous major was removed.
+- [ ] Update the wiki for any references to anything deprecated/removed.
+- [ ] Change `Config::STABILITY` from "dev" to "stable" for the branch for the new major. - PR #xxx
+
+### Prepare changelog
+
+- [ ] Prepare changelog for the release and submit the PR. - PR #xxx
+    - Based on the tickets in the milestone.
+    - Double-check that any issues which were closed by PRs included in the release, have the milestone set.
+    - Compare with auto-generated release notes to ensure nothing is missed.
+    - :pencil2: Remember to add a release link at the bottom!
+- [ ] Prepare extra sections for the GH release notes.
+    - Use "New contributors" list from the auto-generated notes.
+    - Use the milestone to gather the stats.
+    - Add sponsor link.
+    - Remove square brackets from all ticket links or make them proper full links (as GH markdown parser doesn't parse these correctly).
+    - Change all contributor links to full inline links (as GH markdown parser on the Releases page doesn't parse these correctly).
+    ```md
+---
+
+### New Contributors
+
+The PHP_CodeSniffer project is happy to welcome the following new contributors:
+@...., @....
+
+### Statistics
+
+**Closed**: # issues
+**Merged**: ## pull requests
+
+If you like to stay informed about releases and more, follow [@phpcs on Mastodon](https://phpc.social/@phpcs) or [@PHP_CodeSniffer on X](https://x.com/PHP_CodeSniffer).
+
+Please consider [funding the PHP_CodeSniffer project](https://opencollective.com/php_codesniffer). If you already do so: thank you!
+    ```
+
+### Milestone
+
+- [ ] Close the milestone
+- [ ] Open a new milestone for the next release
+- [ ] If any open PRs/issues which were milestoned for this release did not make it into the release, update their milestone.
+
+
+## Release
+
+- [ ] Merge the changelog PR.
+    For now, cherrypick the changelog to the 4.0 branch.
+- [ ] Make sure all CI builds for `master` are green.
+- [ ] Create a tag for the release & push it.
+- [ ] Make sure all CI builds are green.
+- [ ] Download the PHAR files from the GH Actions test build page.
+- [ ] Sign the PHAR files using:
+    ```bash
+    gpg -u [email protected] --detach-sign --output phpcs.phar.asc phpcs.phar
+    gpg -u [email protected] --detach-sign --output phpcbf.phar.asc phpcbf.phar
+    gpg -u [email protected] --detach-sign --output phpcs-x.x.x.phar.asc phpcs-x.x.x.phar
+    gpg -u [email protected] --detach-sign --output phpcbf-x.x.x.phar.asc phpcbf-x.x.x.phar
+    ```
+    - If, for whatever reason, the key is no longer available or has expired:
+      -> generate a new key following the steps here: <https://phar.io/howto/generate-gpg-key.html>.
+      -> upload the new key following the steps here: <https://phar.io/howto/uploading-public-keys.html>.
+      -> update the key information in the README x 3.
+      -> update the key info in the verify-release GHA workflow.
+- [ ] Get the SHA of the files for the phive.xml file
+    ```bash
+    # Linux
+    sha256sum ./phpcs-x.x.x.phar
+    sha256sum ./phpcbf-x.x.x.phar
+
+    # Windows
+    certutil -hashfile ./phpcs-x.x.x.phar SHA256
+    certutil -hashfile ./phpcbf-x.x.x.phar SHA256
+    ```
+- Update the `gh-pages` branch:
+    - [ ] Add the new release to the `phive.xml` file.
+    - [ ] Add the versioned PHAR files + keys in PHAR dir.
+    - [ ] Add the unversioned PHAR files + keys in root dir.
+    - [ ] Verify the attestations of the PHAR files.
+    ```bash
+    gh attestation verify phpcs.phar -o PHPCSStandards
+    gh attestation verify phpcbf.phar -o PHPCSStandards
+    gh attestation verify phars/phpcs-x.x.x.phar -o PHPCSStandards
+    gh attestation verify phars/phpcbf-x.x.x.phar -o PHPCSStandards
+    ```
+    - [ ] Commit & push the changes.
+    - [ ] Verify that the website regenerated correctly and that the phars can be downloaded.
+- [ ] Create a release & copy & paste the changelog to it.
+    - [ ] Upload the unversioned PHAR files + asc files to the release.
+    - [ ] Announce the release in the discussions forum by checking the checkbox at the bottom of the release page.
+- [ ] Make sure all CI builds are green, including the verify-release workflow.
+
+
+## After Release
+
+- [ ] Update the version number in the `Config::VERSION` class constant in the `src/Config.php` file to the _next_ (patch) version.
+    This can always be adjusted again later if needs be if it is decided that the next version will be a minor/major, but at least for dev
+    it should clearly show that this is bleeding edge/unreleased.
+- [ ] Close release announcement in the "Discussions" for previous minors (leave the announcements related to the current minor open).
+
+
+### Publicize
+
+- [ ] Post on Mastodon about the release (official account).
+- [ ] Post on X about the release (official account).
+- [ ] Post on LinkedIn (personal account).
diff --git a/.github/workflows/build-phar.yml b/.github/workflows/build-phar.yml
@@ -1,14 +1,33 @@
 name: Build PHARs
 
 on:
-  # Run on pushes to master and on all pull requests.
+  # Run on pushes to master and on pull requests which touch files used when building the PHARs.
   # Prevent the build from running when there are only irrelevant changes.
   push:
     branches:
       - master
-    paths-ignore:
-      - '**.md'
+    paths:
+      - '.github/workflows/build-phar.yml'
+      - '.github/workflows/reusable-build-phar.yml'
+      - 'scripts/build-phar.php'
+      - 'autoload.php'
+      - 'src/Config.php'
+      - 'src/Exceptions/RuntimeException.php'
+      - 'src/Exceptions/TokenizerException.php'
+      - 'src/Tokenizers/PHP.php'
+      - 'src/Util/Tokens.php'
   pull_request:
+    paths:
+      - '.github/workflows/build-phar.yml'
+      - '.github/workflows/reusable-build-phar.yml'
+      - 'scripts/build-phar.php'
+      - 'autoload.php'
+      - 'src/Config.php'
+      - 'src/Exceptions/RuntimeException.php'
+      - 'src/Exceptions/TokenizerException.php'
+      - 'src/Tokenizers/PHP.php'
+      - 'src/Util/Tokens.php'
+
   # Allow manually triggering the workflow.
   workflow_dispatch:
 
@@ -20,35 +39,13 @@ concurrency:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
-
     strategy:
       matrix:
         # Deliberately missing PHP 8.0 as that PHAR is build and used in the test workflow.
-        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.1', '8.2', '8.3', '8.4']
+        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.1', '8.2', '8.3', '8.4', 'nightly']
 
     name: "Build Phar on PHP: ${{ matrix.php }}"
 
-    continue-on-error: ${{ matrix.php == '8.4' }}
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: none
-          ini-values: phar.readonly=Off, error_reporting=-1, display_errors=On
-
-      - name: Build the phars
-        run: php scripts/build-phar.php
-
-      # Both the below only check a file which is rarely changed and therefore unlikely to have issues.
-      # This test is about testing that the phars are functional, *not* about whether the code style complies.
-      - name: 'PHPCS: check code style using the Phar file to test the Phar is functional'
-        run: php phpcs.phar ./scripts
-
-      - name: 'PHPCBF: fix code style using the Phar file to test the Phar is functional'
-        run: php phpcbf.phar ./scripts
+    uses: ./.github/workflows/reusable-build-phar.yml
+    with:
+      phpVersion: ${{ matrix.php }}
diff --git a/.github/workflows/happy-new-year.yml b/.github/workflows/happy-new-year.yml
@@ -35,15 +35,15 @@ jobs:
       - name: Set branches to use
         id: branches
         run: |
-          echo "BASE=master" >> $GITHUB_OUTPUT
-          echo "PR_BRANCH=feature/squiz-filecomment-update-copyright-year" >> $GITHUB_OUTPUT
+          echo "BASE=master" >> "$GITHUB_OUTPUT"
+          echo "PR_BRANCH=feature/squiz-filecomment-update-copyright-year" >> "$GITHUB_OUTPUT"
 
       # Using "Tomorrow" to prevent accidentally getting last year if the server is not using UTC.
       - name: Grab the new year
         id: year
         run: |
-          echo "PREVIOUS_YEAR=$(date --date="last month" -u "+%Y")" >> $GITHUB_OUTPUT
-          echo "NEW_YEAR=$(date --date="tomorrow" -u "+%Y")" >> $GITHUB_OUTPUT
+          echo "PREVIOUS_YEAR=$(date --date="last month" -u "+%Y")" >> "$GITHUB_OUTPUT"
+          echo "NEW_YEAR=$(date --date="tomorrow" -u "+%Y")" >> "$GITHUB_OUTPUT"
 
       - name: "Debug info: Show years"
         run: "echo current year: ${{ steps.year.outputs.NEW_YEAR }} - previous year: ${{ steps.year.outputs.PREVIOUS_YEAR }}"

diff --git a/.github/workflows/label-remove-outdated.yml b/.github/workflows/label-remove-outdated.yml
@@ -23,6 +23,7 @@ jobs:
           labels: |
             Status: awaiting feedback
             Status: close candidate
+            Status: help wanted
             Status: needs investigation
             Status: triage
 
@@ -40,8 +41,10 @@ jobs:
             Status: awaiting feedback
             Status: close candidate
             Status: has merge conflict
+            Status: help wanted
             Status: needs investigation
             Status: triage
+            Status: waiting for opinions
 
   on-pr-close:
     runs-on: ubuntu-latest
@@ -56,5 +59,6 @@ jobs:
           labels: |
             Status: awaiting feedback
             Status: close candidate
+            Status: help wanted
             Status: needs investigation
             Status: triage
diff --git a/.github/workflows/phpstan.yml b/.github/workflows/phpstan.yml
@@ -20,28 +20,4 @@ concurrency:
 jobs:
   phpstan:
     name: "PHPStan"
-
-    runs-on: "ubuntu-latest"
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: 'latest'
-          coverage: none
-          tools: phpstan
-
-      # Install dependencies and handle caching in one go.
-      # Dependencies need to be installed to make sure the PHPUnit classes are recognized.
-      # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
-      - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
-        with:
-          # Bust the cache at least once a month - output format: YYYY-MM.
-          custom-cache-suffix: $(date -u "+%Y-%m")
-
-      - name: Run PHPStan
-        run: phpstan analyse
+    uses: PHPCSStandards/.github/.github/workflows/reusable-phpstan.yml@main