[changelog] Auto-create Dependabot entries before validation (#186) (#189)

* [changelog] Auto-create Dependabot entries before validation (#186)

* Update wiki submodule pointer for PR #189

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/actions/changelog/create-dependabot-entry/action.yml

@@ -0,0 +1,41 @@
+name: Create Dependabot Changelog Entry
+description: Create and push a minimal changelog entry for a same-repository Dependabot pull request when the branch still lacks one.
+
+inputs:
+  changelog-file:
+    description: Managed changelog path.
+    required: true
+  base-ref:
+    description: Base branch reference used for changelog comparison.
+    required: true
+  head-ref:
+    description: Pull request head branch ref.
+    required: true
+  pull-request-number:
+    description: Pull request number.
+    required: true
+  pull-request-title:
+    description: Pull request title used as the fallback changelog message source.
+    required: true
+
+outputs:
+  created:
+    description: Whether a changelog entry was created and pushed.
+    value: ${{ steps.create.outputs.created }}
+  message:
+    description: Generated changelog entry message, or empty when no entry was needed.
+    value: ${{ steps.create.outputs.message }}
+
+runs:
+  using: composite
+  steps:
+    - id: create
+      name: Create entry when missing
+      shell: bash
+      env:
+        INPUT_CHANGELOG_FILE: ${{ inputs.changelog-file }}
+        INPUT_BASE_REF: ${{ inputs.base-ref }}
+        INPUT_HEAD_REF: ${{ inputs.head-ref }}
+        INPUT_PULL_REQUEST_NUMBER: ${{ inputs.pull-request-number }}
+        INPUT_PULL_REQUEST_TITLE: ${{ inputs.pull-request-title }}
+      run: ${{ github.action_path }}/run.sh

.github/actions/changelog/create-dependabot-entry/run.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if composer dev-tools changelog:check -- --file="${INPUT_CHANGELOG_FILE}" --against="origin/${INPUT_BASE_REF}" >/dev/null 2>&1; then
+    echo "created=false" >> "$GITHUB_OUTPUT"
+    exit 0
+fi
+
+git fetch --no-tags --depth=1 origin "+refs/heads/${INPUT_HEAD_REF}:refs/remotes/origin/${INPUT_HEAD_REF}"
+git switch -C "${INPUT_HEAD_REF}" "refs/remotes/origin/${INPUT_HEAD_REF}"
+git config user.name "github-actions[bot]"
+git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+entry_message="$(php -r 'require "vendor/autoload.php"; $resolver = new \FastForward\DevTools\Changelog\DependabotChangelogEntryMessageResolver(); echo $resolver->resolve(getenv("INPUT_PULL_REQUEST_TITLE") ?: "", (int) (getenv("INPUT_PULL_REQUEST_NUMBER") ?: 0));')"
+
+composer dev-tools changelog:entry -- --type=changed --file="${INPUT_CHANGELOG_FILE}" "${entry_message}"
+git add "${INPUT_CHANGELOG_FILE}"
+git commit -m "Add changelog entry for Dependabot PR #${INPUT_PULL_REQUEST_NUMBER}"
+git push origin "HEAD:${INPUT_HEAD_REF}"
+
+{
+    echo "created=true"
+    printf 'message=%s\n' "${entry_message}"
+} >> "$GITHUB_OUTPUT"

.github/wiki

@@ -92,6 +92,10 @@ jobs:
         env:
             CHANGELOG_FILE: ${{ inputs.changelog-file || 'CHANGELOG.md' }}
             CHANGELOG_ROOT_VERSION: ${{ github.event.pull_request.head.ref && format('dev-{0}', github.event.pull_request.head.ref) || 'dev-main' }}
+            BASE_REF: ${{ github.event.pull_request.base.ref }}
+            HEAD_REF: ${{ github.event.pull_request.head.ref }}
+            PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+            PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}
 
         steps:
             - uses: actions/checkout@v6
@@ -114,13 +118,20 @@ jobs:
                   install-options: --prefer-dist --no-progress --no-interaction --no-plugins --no-scripts
 
             - name: Fetch base branch reference
-              env:
-                  BASE_REF: ${{ github.event.pull_request.base.ref }}
               run: git fetch --no-tags --depth=1 origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}"
 
+            - name: Create Dependabot changelog entry when missing
+              id: dependabot_entry
+              if: ${{ (github.event.pull_request.user.login == 'dependabot[bot]' || github.event.pull_request.user.login == 'app/dependabot' || startsWith(github.event.pull_request.head.ref, 'dependabot/')) && github.event.pull_request.head.repo.full_name == github.repository }}
+              uses: ./.dev-tools-actions/.github/actions/changelog/create-dependabot-entry
+              with:
+                  changelog-file: ${{ env.CHANGELOG_FILE }}
+                  base-ref: ${{ env.BASE_REF }}
+                  head-ref: ${{ env.HEAD_REF }}
+                  pull-request-number: ${{ env.PULL_REQUEST_NUMBER }}
+                  pull-request-title: ${{ env.PULL_REQUEST_TITLE }}
+
             - name: Verify changelog update
-              env:
-                  BASE_REF: ${{ github.event.pull_request.base.ref }}
               run: composer dev-tools changelog:check -- --file="${CHANGELOG_FILE}" --against="origin/${BASE_REF}"
 
             - uses: ./.dev-tools-actions/.github/actions/summary/write
@@ -129,7 +140,9 @@ jobs:
                       ## Changelog Validation Summary
 
                       - Changelog file: `${{ env.CHANGELOG_FILE }}`
-                      - Compared base ref: `origin/${{ github.event.pull_request.base.ref }}`
+                      - Compared base ref: `origin/${{ env.BASE_REF }}`
+                      - Dependabot fallback entry created: `${{ steps.dependabot_entry.outputs.created || 'false' }}`
+                      - Dependabot fallback entry message: `${{ steps.dependabot_entry.outputs.message || 'not needed' }}`
                       - Validation result: success
 
     prepare_release_pull_request:

.github/workflows/changelog.yml

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Auto-create and push minimal changelog entries for same-repository Dependabot pull requests before changelog validation reruns (#186)
+
 ## [1.20.0] - 2026-04-23
 
 ### Changed

CHANGELOG.md

@@ -147,6 +147,9 @@ The packaged changelog workflow consumes these commands in two places:
 
 - pull-request validation runs ``changelog:check`` against the base branch to
   require a meaningful changelog update;
+- Dependabot pull-request validation MAY create one minimal ``changed`` entry
+  from the pull-request title before re-running ``changelog:check`` so the
+  branch keeps a persisted release note without manual intervention;
 - manual release preparation uses ``changelog:next-version`` and
   ``changelog:promote`` to create a release pull request, then
   ``changelog:show`` to publish the merged section as GitHub release notes.

docs/commands/changelog.rst

@@ -161,6 +161,9 @@ wrapper in ``resources/github-actions/changelog.yml``.
     *   Uses ``fetch-depth: 0`` so the base branch reference can be compared
         safely.
     *   Fetches the base branch changelog reference.
+    *   For same-repository Dependabot pull requests, creates and pushes a
+        minimal ``Unreleased`` changelog entry derived from the pull request
+        title when the branch has not added one yet.
     *   Runs ``composer dev-tools changelog:check -- --against=<base-ref>`` against the base ref.
     *   Fails when a normal non-release branch does not add a meaningful ``Unreleased`` change.
     *   Skips the validation job for pull requests whose head branch matches the configured ``release-branch-prefix``, because release-preparation branches intentionally leave ``Unreleased`` empty after promotion.

docs/usage/github-actions.rst

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Changelog;
+
+/**
+ * Normalizes minimal changelog entry messages for Dependabot pull requests.
+ */
+final readonly class DependabotChangelogEntryMessageResolver
+{
+    /**
+     * @param string $title
+     * @param int $pullRequestNumber
+     *
+     * @return string
+     */
+    public function resolve(string $title, int $pullRequestNumber): string
+    {
+        $message = \preg_replace('/\s+/', ' ', \trim($title)) ?? \trim($title);
+        $message = \rtrim($message, " \t\n\r\0\x0B.");
+
+        if (\preg_match('/\(#\d+\)$/', $message) === 1) {
+            return $message;
+        }
+
+        return \sprintf('%s (#%d)', $message, $pullRequestNumber);
+    }
+}

src/Changelog/DependabotChangelogEntryMessageResolver.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Tests\Changelog;
+
+use FastForward\DevTools\Changelog\DependabotChangelogEntryMessageResolver;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(DependabotChangelogEntryMessageResolver::class)]
+final class DependabotChangelogEntryMessageResolverTest extends TestCase
+{
+    #[Test]
+    public function resolveWillAppendThePullRequestNumberWhenTheTitleHasNoSuffix(): void
+    {
+        $resolver = new DependabotChangelogEntryMessageResolver();
+
+        self::assertSame(
+            'GitHub Actions(deps): Bump actions/github-script from 8 to 9 (#183)',
+            $resolver->resolve("  GitHub Actions(deps):  Bump actions/github-script from 8 to 9 \n", 183),
+        );
+    }
+
+    #[Test]
+    public function resolveWillPreserveAnExistingPullRequestSuffix(): void
+    {
+        $resolver = new DependabotChangelogEntryMessageResolver();
+
+        self::assertSame(
+            'Bump symfony/console from 7.3.0 to 7.3.1 (#123)',
+            $resolver->resolve('Bump symfony/console from 7.3.0 to 7.3.1 (#123)', 123),
+        );
+    }
+
+    #[Test]
+    public function resolveWillTrimTrailingPunctuationBeforeAppendingTheSuffix(): void
+    {
+        $resolver = new DependabotChangelogEntryMessageResolver();
+
+        self::assertSame(
+            'Bump peter-evans/create-pull-request from 7 to 8 (#181)',
+            $resolver->resolve('Bump peter-evans/create-pull-request from 7 to 8.', 181),
+        );
+    }
+}