Merge v1.18 into v1.19 (#1316)

.github/workflows/release.yml

@@ -0,0 +1,127 @@
+name: "Release New Version"
+run-name: "Release ${{ inputs.version }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "The version to be released. This is checked for consistency with the branch name and configuration"
+        required: true
+        type: "string"
+      jira-version-number:
+        description: "JIRA version ID (e.g. 54321)"
+        required: true
+        type: "string"
+
+env:
+  # TODO: Use different token
+  GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }}
+  GIT_AUTHOR_NAME: "DBX PHP Release Bot"
+  GIT_AUTHOR_EMAIL: "[email protected]"
+  default-release-message: |
+    The PHP team is happy to announce that version {0} of the MongoDB PHP library is now available.
+
+    **Release Highlights**
+
+    TODO: one or more paragraphs describing important changes in this release
+
+    A complete list of resolved issues in this release may be found in [JIRA](https://jira.mongodb.org/secure/ReleaseNote.jspa?version={1}&projectId=12483).
+
+    **Documentation**
+
+    Documentation for this library may be found in the [PHP Library Manual](https://mongodb.com/docs/php-library/current/).
+
+    **Installation**
+
+    This library may be installed or upgraded with:
+    
+      composer require mongodb/mongodb:{0}
+      
+    Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php).
+
+jobs:
+  prepare-release:
+    name: "Prepare release"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Create release output"
+        run: echo '🎬 Release process for version ${{ inputs.version }} started by @${{ github.triggering_actor }}' >> $GITHUB_STEP_SUMMARY
+
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          token: ${{ env.GH_TOKEN }}
+
+      - name: "Store version numbers in env variables"
+        run: |
+          echo RELEASE_VERSION=${{ inputs.version }} >> $GITHUB_ENV
+          echo RELEASE_BRANCH=v$(echo ${{ inputs.version }} | cut -d '.' -f-2) >> $GITHUB_ENV
+
+      - name: "Ensure release tag does not already exist"
+        run: |
+          if [[ $(git tag -l ${RELEASE_VERSION}) == ${RELEASE_VERSION} ]]; then
+            echo '❌ Release failed: tag for version ${{ inputs.version }} already exists' >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+
+      - name: "Fail if branch names don't match"
+        if: ${{ github.ref_name != env.RELEASE_BRANCH }}
+        run: |
+          echo '❌ Release failed due to branch mismatch: expected ${{ inputs.version }} to be released from ${{ env.RELEASE_BRANCH }}, got ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY
+          exit 1
+
+      #
+      # Preliminary checks done - commence the release process
+      #
+
+      - name: "Set git author information"
+        run: |
+          git config user.name "${GIT_AUTHOR_NAME}"
+          git config user.email "${GIT_AUTHOR_EMAIL}"
+
+      # Create a draft release with release message filled in
+      - name: "Prepare release message"
+        run: |
+          cat > release-message <<'EOL'
+          ${{ format(env.default-release-message, inputs.version, inputs.jira-version-number) }}
+          EOL
+
+      - name: "Create draft release"
+        run: echo "RELEASE_URL=$(gh release create ${{ inputs.version }} --target ${{ github.ref_name }} --title "${{ inputs.version }}" --notes-file release-message --draft)" >> "$GITHUB_ENV"
+
+      # This step creates the signed release tag
+      - name: "Create release tag"
+        uses: mongodb-labs/drivers-github-tools/garasign/git-sign@main
+        with:
+          command: "git tag -m 'Release ${{ inputs.version }}' -s --local-user=${{ vars.GPG_KEY_ID }} ${{ inputs.version }}"
+          garasign_username: ${{ secrets.GRS_CONFIG_USER1_USERNAME }}
+          garasign_password: ${{ secrets.GRS_CONFIG_USER1_PASSWORD }}
+          artifactory_username: ${{ secrets.ARTIFACTORY_USER }}
+          artifactory_password: ${{ secrets.ARTIFACTORY_PASSWORD }}
+
+      # TODO: Manually merge using ours strategy. This avoids merge-up pull requests being created
+      # Process is:
+      # 1. switch to next branch (according to merge-up action)
+      # 2. merge release branch using --strategy=ours
+      # 3. push next branch
+      # 4. switch back to release branch, then push
+
+      - name: "Push changes from release branch"
+        run: git push
+
+      - name: "Prepare release message"
+        run: |
+          cat > release-message <<'EOL'
+          ${{ format(env.default-release-message, inputs.version, inputs.jira-version-number) }}
+          EOL
+          cat changelog >> release-message
+
+      # Pushing the release tag starts build processes that then produce artifacts for the release
+      - name: "Push release tag"
+        run: git push origin ${{ inputs.version }}
+
+      - name: "Set summary"
+        run: |
+          echo '🚀 Created tag and drafted release for version [${{ inputs.version }}](${{ env.RELEASE_URL }})' >> $GITHUB_STEP_SUMMARY
+          echo '✍️ You may now update the release notes and publish the release when ready' >> $GITHUB_STEP_SUMMARY

README.md

@@ -44,6 +44,26 @@ that the `mongodb` extension be installed:
 Additional installation instructions for the extension may be found in its
 [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php).
 
+## Release Integrity
+
+Releases are created automatically and the resulting release tag is signed using
+the [PHP team's GPG key](https://pgp.mongodb.com/php-driver.asc). To verify the
+tag signature, download the key and import it using `gpg`:
+
+```shell
+gpg --import php-driver.asc
+```
+
+Then, in a local clone, verify the signature of a given tag (e.g. `1.19.0`):
+
+```shell
+git show --show-signature 1.19.0
+```
+
+> [!NOTE]
+> Composer does not support verifying signatures as part of its installation
+> process.
+
 ## Reporting Issues
 
 Issues pertaining to the library should be reported in the