[TASK] Release through pull request and tag, add tests-passed check

.ddev/commands/web/next

@@ -66,18 +66,19 @@ major=${lastTagParts[0]}
 minor=${lastTagParts[1]}
 patch=${lastTagParts[2]}
 
+# Not `((x++))` - it returns status 1 when x is 0, which stops the script because of `set -e`
 case $versionType in
     major)
-        ((major++))
+        major=$((major + 1))
         minor=0
         patch=0
         ;;
     minor)
-        ((minor++))
+        minor=$((minor + 1))
         patch=0
         ;;
     patch)
-        ((patch++))
+        patch=$((patch + 1))
         ;;
 esac
 
@@ -88,12 +89,33 @@ if git rev-parse "$NEXT_TAG" >/dev/null 2>&1; then
     exit 1
 fi
 
+# Version files are updated through a pull request (default branch can be protected), so the script runs twice:
+# 1st run updates version files and prints commands to open a pull request with them,
+# 2nd run (after the pull request is merged) finds the files up to date and prints commands to push the tag only.
+# The version is computed from the last tag, so the 2nd run computes the same version as the 1st one.
+CURRENT_VERSION=$(sed -n "s/.*'version' => '\([0-9]\+\.[0-9]\+\.[0-9]\+\)'.*/\1/p" ./ext_emconf.php | head -1)
+if [ "$CURRENT_VERSION" != "$lastTag" ] && [ "$CURRENT_VERSION" != "$NEXT_TAG" ]; then
+    echo "Error: ext_emconf.php has version '$CURRENT_VERSION', which is neither the last tag '$lastTag' nor the next version '$NEXT_TAG'."
+    echo "Run 'ddev next' with the version type ('patch', 'minor' or 'major') which gives '$CURRENT_VERSION'."
+    exit 1
+fi
+
 # Update files with the new version
 sed -i "s/'version' => '[0-9]\+\.[0-9]\+\.[0-9]\+'/'version' => '$NEXT_TAG'/g" ./ext_emconf.php
 sed -i -E "s/(\"version\": \")[0-9]+\.[0-9]+\.[0-9]+(\")/\1$NEXT_TAG\2/" ./composer.json
 sed -i "s/release=\"[0-9]\+\.[0-9]\+\.[0-9]\+\"/release=\"$NEXT_TAG\"/g" ./Documentation/guides.xml
-sed -i'' -E "s/(<project[^>]* version=\")[^\"]+(\")/\1$NEXT_TAG\2/" ./Documentation/guides.xml
+# `version` of the documentation is "major.minor", the <project> element spans several lines
+sed -i -E "/<project/,/>/ s/(\s)version=\"[^\"]*\"/\1version=\"$major.$minor\"/" ./Documentation/guides.xml
+
+VERSION_FILES="Documentation/guides.xml ext_emconf.php composer.json"
+
+if ! git diff --quiet -- $VERSION_FILES; then
+    echo "Version files are updated to '$NEXT_TAG'. Copy the command below and run it to push them to a new branch:"
+    echo "zsh -e -c \"git switch -c 'version-$NEXT_TAG'; git add $VERSION_FILES; git commit -m 'Tag version $NEXT_TAG'; git push -u origin 'version-$NEXT_TAG'\""
+    echo "Then open a pull request to '$DEFAULT_BRANCH', merge it, switch to '$DEFAULT_BRANCH', run 'git pull' and run 'ddev next $versionType' again to tag the version."
+    exit 0
+fi
 
 # Prepare command to tag the new version
-echo "Copy the command below and run it to tag the new version:"
-echo "zsh -e -c \"git add Documentation/guides.xml ext_emconf.php composer.json; git commit -m 'Tag version $NEXT_TAG'; git tag -a '$NEXT_TAG' -m 'Version $NEXT_TAG' -s; git push origin $DEFAULT_BRANCH '$NEXT_TAG'\""
+echo "Version files are up to date. Copy the command below and run it to tag the new version:"
+echo "zsh -e -c \"git tag -a '$NEXT_TAG' -m 'Version $NEXT_TAG' -s; git push origin '$NEXT_TAG'\""

.github/workflows/tests.yml

@@ -56,3 +56,12 @@ jobs:
             ddev composer config --global github-oauth.github.com ${{ env.GH_TOKEN }}
           fi
       - run: ddev ci ${{ matrix.typo3 }} ${{ matrix.php }} ${{ matrix.composer }}
+
+  # Single check to require in branch protection - names of the matrix jobs change with the matrix.
+  # `always()` - without it the job is skipped when a test fails, and a skipped required check counts as passed.
+  tests-passed:
+    if: always()
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - run: '[ "${{ needs.test.result }}" = "success" ]'

Documentation/Miscellaneous/Development/CommandsList/Index.rst

@@ -121,23 +121,42 @@ Example:
 .. _development_commands_list_ddev_next:
 :bash:`ddev next [major|minor|patch]`
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-This command will help to tag next release of extension.
+This command helps to release the next version of the extension. The default branch can be protected (changes only
+through pull requests), so the version files are changed in a pull request and the command is run twice.
 
-It does several checks. Amongst other it:
+It does several checks first:
 
 1. Checks if you are on default branch.
-2. Checks if you are are up to date with remote default branch.
+2. Checks if you are up to date with remote default branch.
 3. Checks if you do not have any not pushed changes to remote.
 4. Checks validity of last tag.
-5. Increase version in few files:
+5. Checks if the version in :file:`/ext_emconf.php` is the last tag or the next version - otherwise you passed another
+   version type than in the first run.
 
-   * :file:`/ext_emconf.php`
-   * :file:`/Documentation/guides.xml`
+The next version is computed from the last tag, so both runs compute the same version.
 
-After all checks it outputs a command you need to run to push changes and tag to git.
+**First run** updates the version in:
 
-Example output:
+* :file:`/ext_emconf.php`
+* :file:`/composer.json`
+* :file:`/Documentation/guides.xml` (``release`` - full version, ``version`` - major and minor)
+
+and outputs a command which pushes them to a new branch:
+
+.. code-block:: bash
+
+    zsh -e -c "git switch -c 'version-5.1.0'; git add Documentation/guides.xml ext_emconf.php composer.json; git commit -m 'Tag version 5.1.0'; git push -u origin 'version-5.1.0'"
+
+Open a pull request from this branch to the default branch and merge it.
+
+**Second run** - on the updated default branch (:bash:`git pull`), with the same version type. The version files are up
+to date, so it outputs a command which pushes the tag only:
 
 .. code-block:: bash
 
-    git add Documentation/guides.xml ext_emconf.php && git commit -m 'Tag version 3.1.0' && git tag -a '3.1.0' -m 'Version 3.1.0' -s && git push origin main --tags
+    zsh -e -c "git tag -a '5.1.0' -m 'Version 5.1.0' -s; git push origin '5.1.0'"
+
+Pushing the tag starts the release workflow (GitHub release and publishing to TER).
+
+When the version files are already updated in the branch merged to the default branch (e.g. a release branch), the first
+run outputs the tag command right away.