Merge branch 'master' into feature/support-generics

Author: tm1000

.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).

.github/workflows/build-phar.yml

@@ -8,6 +8,7 @@ on:
       - master
     paths:
       - '.github/workflows/build-phar.yml'
+      - '.github/workflows/reusable-build-phar.yml'
       - 'scripts/build-phar.php'
       - 'autoload.php'
       - 'src/Config.php'
@@ -18,6 +19,7 @@ on:
   pull_request:
     paths:
       - '.github/workflows/build-phar.yml'
+      - '.github/workflows/reusable-build-phar.yml'
       - 'scripts/build-phar.php'
       - 'autoload.php'
       - 'src/Config.php'
@@ -37,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', '8.5']
+        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.5' }}
-
-    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 }}

.github/workflows/quicktest.yml

@@ -27,12 +27,12 @@ jobs:
 
     strategy:
       matrix:
-        os: ['ubuntu-latest', 'windows-latest']
+        os: ['ubuntu-24.04-arm', 'windows-latest']
         php: ['7.2', 'latest']
 
         include:
           - php: '5.4'
-            os: 'ubuntu-latest'
+            os: 'ubuntu-24.04-arm'
             custom_ini: false
           # Installing on Windows with PHP 5.4 runs into all sorts of problems with Composer.
           # See this issue for more context (yes, I've seen this problem before):
@@ -41,7 +41,7 @@ jobs:
             os: 'windows-latest'
             custom_ini: false
 
-    name: "QuickTest: PHP ${{ matrix.php }} (${{ matrix.os == 'ubuntu-latest' && 'Linux' || 'Win'  }})"
+    name: "QuickTest: PHP ${{ matrix.php }} (${{ matrix.os == 'windows-latest' && 'Win' || 'Linux ARM' }})"
 
     steps:
       - name: Prepare git to leave line endings alone

.github/workflows/reusable-build-phar.yml

@@ -0,0 +1,81 @@
+name: Build PHAR files
+
+on:
+  workflow_call:
+    inputs:
+      phpVersion:
+        description: "The PHP version to use. Defaults to PHP 8.0 as used for the releases."
+        type: string
+        required: false
+        default: '8.0'
+      uploadArtifacts:
+        description: "Whether or not to upload the artifacts. Defaults to false."
+        type: boolean
+        required: false
+        default: false
+      retentionDays:
+        description: "How long uploaded artifacts should remain available (in days). Defaults to 1 day."
+        type: string
+        required: false
+        default: 1
+      createAttestations:
+        description: "Whether or not to create attestations for the artifacts. Defaults to false."
+        type: boolean
+        required: false
+        default: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: "Build Phar on PHP: ${{ inputs.phpVersion }}"
+
+    continue-on-error: ${{ inputs.phpVersion == 'nightly' }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ inputs.phpVersion }}
+          coverage: none
+          ini-values: phar.readonly=Off, error_reporting=-1, display_errors=On
+
+      - name: Build the phar files
+        run: php scripts/build-phar.php
+
+      # Provide provenance for generated binaries.
+      - name: Generate artifact attestations
+        if: ${{ inputs.createAttestations == true }}
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: |
+            ${{ github.workspace }}/phpcs.phar
+            ${{ github.workspace }}/phpcbf.phar
+
+      - name: Upload the PHPCS phar
+        if: ${{ inputs.uploadArtifacts == true }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpcs-phar
+          path: ./phpcs.phar
+          if-no-files-found: error
+          retention-days: ${{ inputs.retentionDays }}
+
+      - name: Upload the PHPCBF phar
+        if: ${{ inputs.uploadArtifacts == true }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpcbf-phar
+          path: ./phpcbf.phar
+          if-no-files-found: error
+          retention-days: ${{ inputs.retentionDays }}
+
+      # 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

.github/workflows/test.yml

@@ -22,62 +22,20 @@ jobs:
       group: ${{ github.workflow }}-${{ github.job }}-${{ github.ref }}
       cancel-in-progress: true
 
-    runs-on: ubuntu-latest
     name: "Build Phar on PHP: 8.0"
 
     permissions:
       id-token: write
       contents: read
       attestations: write
 
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.0'
-          coverage: none
-          ini-values: phar.readonly=Off, error_reporting=-1, display_errors=On
-
-      - name: Build the phar
-        run: php scripts/build-phar.php
-
-      # Provide provenance for generated binaries.
+    uses: ./.github/workflows/reusable-build-phar.yml
+    with:
+      uploadArtifacts: true
+      retentionDays: 28
       # Only attests the build artifacts which will be used in the published releases as per the guidelines in "what to attest".
       # https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds
-      - name: Generate artifact attestations
-        if: ${{ github.ref_type == 'tag' }}
-        uses: actions/attest-build-provenance@v1
-        with:
-          subject-path: |
-            ${{ github.workspace }}/phpcs.phar
-            ${{ github.workspace }}/phpcbf.phar
-
-      - name: Upload the PHPCS phar
-        uses: actions/upload-artifact@v4
-        with:
-          name: phpcs-phar
-          path: ./phpcs.phar
-          if-no-files-found: error
-          retention-days: 28
-
-      - name: Upload the PHPCBF phar
-        uses: actions/upload-artifact@v4
-        with:
-          name: phpcbf-phar
-          path: ./phpcbf.phar
-          if-no-files-found: error
-          retention-days: 28
-
-      # 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
+      createAttestations: ${{ github.ref_type == 'tag' }}
 
   test:
     # Cancels all previous runs of this particular job for the same branch that have not yet completed.
@@ -190,6 +148,7 @@ jobs:
         run: php "vendor/bin/phpunit" tests/AllTests.php --no-coverage
 
       - name: 'PHPUnit: run select tests in CBF mode'
+        if: ${{ matrix.skip_tests != true }}
         run: php "vendor/bin/phpunit" tests/AllTests.php --group CBF --exclude-group nothing --no-coverage
         env:
           PHP_CODESNIFFER_CBF: '1'