feat(release): add changelog entry, GitHub Releases, lastPublished, and RELEASING.md

Author: Fabiana Severin

.github/workflows/release.yml

@@ -27,6 +27,10 @@ on:
         description: 'Next development version override (optional, must end with -SNAPSHOT)'
         required: false
         type: string
+      changelogEntry:
+        description: 'Changelog entry (Markdown bullets, e.g. "- Fix X"). Prepended to the module RELEASE.CHANGELOG.md in the version-bump PR and used as the GitHub Release notes. Required.'
+        required: true
+        type: string
       skip_publish:
         description: 'Skip publish (dry-run validation)'
         required: false
@@ -48,6 +52,7 @@ env:
   MODULE: ${{ github.event.inputs.module }}
   RELEASE_VERSION_INPUT: ${{ github.event.inputs.releaseVersion }}
   DEVELOPMENT_VERSION_INPUT: ${{ github.event.inputs.developmentVersion }}
+  CHANGELOG_ENTRY_INPUT: ${{ github.event.inputs.changelogEntry }}
   # Batch mode + no transfer-progress spam for every Maven call (Maven 3.9+).
   MAVEN_ARGS: "-B --no-transfer-progress"
   AWS_REGION: ${{ vars.AWS_REGION_MAVEN_RELEASE }}
@@ -252,6 +257,34 @@ jobs:
             -Darguments="-gs $MAVEN_SETTINGS -Prelease -Dgpg.keyname=$GPG_KEYNAME -Dgpg.passphrase=$GPG_PASSPHRASE" \
             --file "$MODULE/pom.xml"
 
+      # Bump the lastPublished comment under <version>; rides in the bump PR.
+      - name: Record last published version in POM
+        if: ${{ github.event.inputs.skip_publish != 'true' }}
+        run: |
+          if ! grep -q "<!-- lastPublished:" "$MODULE/pom.xml"; then
+            echo "::notice::$MODULE has no lastPublished comment; skipping"
+            exit 0
+          fi
+          sed -i "s|<!-- lastPublished:.*-->|<!-- lastPublished: ${EFFECTIVE_RELEASE_VERSION} (auto-updated by release.yml) -->|" "$MODULE/pom.xml"
+          git commit -am "chore(release): record ${MODULE} lastPublished=${EFFECTIVE_RELEASE_VERSION}"
+
+      # Prepend the changelog entry so it ships in the version-bump PR. Passed
+      # via env, never interpolated into the script, so it can't inject shell.
+      - name: Prepend changelog entry
+        if: ${{ github.event.inputs.skip_publish != 'true' }}
+        run: |
+          CHANGELOG="$MODULE/RELEASE.CHANGELOG.md"
+          TMP="$(mktemp)"
+          {
+            echo "### $(date +'%B %d, %Y')"
+            echo "\`${EFFECTIVE_RELEASE_VERSION}\`:"
+            printf '%s\n\n' "$CHANGELOG_ENTRY_INPUT"
+            [ -f "$CHANGELOG" ] && cat "$CHANGELOG"
+          } > "$TMP"
+          mv "$TMP" "$CHANGELOG"
+          git add "$CHANGELOG"
+          git commit -m "docs(release): add ${MODULE} ${EFFECTIVE_RELEASE_VERSION} changelog entry"
+
       # main is protected (no direct push), so push the tag and open a PR for
       # the version-bump commits instead. Skipping this would leave the POM on
       # the just-released -SNAPSHOT.
@@ -273,6 +306,22 @@ jobs:
             --title "chore(release): ${MODULE} ${EFFECTIVE_RELEASE_VERSION}" \
             --body "Post-release version bump for ${MODULE} ${EFFECTIVE_RELEASE_VERSION} (already on Maven Central, tag ${TAG} pushed)."
 
+      # GitHub Release on the pushed tag: changelog entry + Central link.
+      - name: Create GitHub Release
+        if: ${{ github.event.inputs.skip_publish != 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${MODULE}-${EFFECTIVE_RELEASE_VERSION}"
+          NOTES="$(mktemp)"
+          {
+            printf '%s\n\n' "$CHANGELOG_ENTRY_INPUT"
+            echo "Published to Maven Central: https://central.sonatype.com/artifact/com.amazonaws/${MODULE}/${EFFECTIVE_RELEASE_VERSION}"
+          } > "$NOTES"
+          gh release create "$TAG" \
+            --title "${MODULE} ${EFFECTIVE_RELEASE_VERSION}" \
+            --notes-file "$NOTES"
+
       - name: Dry-run release (prepare only, no publish)
         if: ${{ github.event.inputs.skip_publish == 'true' }}
         run: |

RELEASING.md

@@ -0,0 +1,50 @@
+# Releasing to Maven Central
+
+How maintainers publish a module using the
+[`Release to Maven Central`](.github/workflows/release.yml) workflow.
+
+Releasable modules: `aws-lambda-java-core`, `aws-lambda-java-events`,
+`aws-lambda-java-events-sdk-transformer`, `aws-lambda-java-log4j2`,
+`aws-lambda-java-serialization`, `aws-lambda-java-tests`.
+
+> `aws-lambda-java-runtime-interface-client` has its own pipeline,
+> [`release-runtime-interface-client.yml`](.github/workflows/release-runtime-interface-client.yml).
+
+## Cutting a release
+
+1. **Actions → Release to Maven Central → Run workflow**, with the branch set to
+   **`main`** (releases only run from `main`).
+2. Fill in the inputs:
+
+   | Input | Required | Notes |
+   |-------|----------|-------|
+   | `module` | yes | Module directory to release. |
+   | `changelogEntry` | yes | Markdown bullets, e.g. `- Fix X`. Added to the module `RELEASE.CHANGELOG.md` and used as the GitHub Release notes. |
+   | `releaseVersion` | no | Defaults to the POM version without `-SNAPSHOT`. |
+   | `developmentVersion` | no | Next dev version; must end with `-SNAPSHOT`. |
+   | `skip_publish` | no | Dry run: build and validate, publish nothing. |
+
+3. Run it and approve the `Release` environment when prompted.
+
+## What it does
+
+1. Validates the branch and resolves the release version from the POM (or your override).
+2. Builds and tests the module.
+3. Publishes to Maven Central and pushes the tag `<module>-<version>`.
+4. Opens a **version-bump PR** into `main` with the next `-SNAPSHOT`, the updated
+   `lastPublished` comment, and your changelog entry.
+5. Creates a GitHub Release on the tag from your changelog entry.
+
+Merge the version-bump PR to return `main` to a clean `-SNAPSHOT` state.
+
+## Dry runs
+
+Set `skip_publish` to build, test, and `release:prepare -DdryRun=true` without
+pushing anything. A `changelogEntry` is still required by the form but unused.
+
+## If a release fails
+
+- **Before publish:** nothing was pushed. Fix and re-run.
+- **After publish:** the Central version is immutable and the tag exists. Don't
+  re-run for the same version (it fails at `release:prepare`); finish the
+  remaining steps by hand (merge the bump PR, or `gh release create`).

aws-lambda-java-core/pom.xml

@@ -6,6 +6,7 @@
   <groupId>com.amazonaws</groupId>
   <artifactId>aws-lambda-java-core</artifactId>
   <version>1.4.1-SNAPSHOT</version>
+  <!-- lastPublished: 1.4.0 (auto-updated by release.yml) -->
   <packaging>jar</packaging>
 
   <name>AWS Lambda Java Core Library</name>

aws-lambda-java-events-sdk-transformer/pom.xml

@@ -6,6 +6,7 @@
   <groupId>com.amazonaws</groupId>
   <artifactId>aws-lambda-java-events-sdk-transformer</artifactId>
   <version>3.1.2-SNAPSHOT</version>
+  <!-- lastPublished: 3.1.1 (auto-updated by release.yml) -->
   <packaging>jar</packaging>
 
   <name>AWS Lambda Java Events SDK Transformer Library</name>

aws-lambda-java-events/pom.xml

@@ -6,6 +6,7 @@
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-lambda-java-events</artifactId>
     <version>3.16.2-SNAPSHOT</version>
+    <!-- lastPublished: 3.16.1 (auto-updated by release.yml) -->
     <packaging>jar</packaging>
 
     <name>AWS Lambda Java Events Library</name>

aws-lambda-java-log4j2/pom.xml

@@ -6,6 +6,7 @@
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-lambda-java-log4j2</artifactId>
     <version>1.6.5-SNAPSHOT</version>
+    <!-- lastPublished: 1.6.4 (auto-updated by release.yml) -->
     <packaging>jar</packaging>
 
     <name>AWS Lambda Java Log4j 2.x Libraries</name>

aws-lambda-java-serialization/pom.xml

@@ -5,6 +5,7 @@
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-lambda-java-serialization</artifactId>
     <version>1.4.2-SNAPSHOT</version>
+    <!-- lastPublished: 1.4.1 (auto-updated by release.yml) -->
     <packaging>jar</packaging>
 
     <name>AWS Lambda Java Runtime Serialization</name>

aws-lambda-java-tests/pom.xml

@@ -6,6 +6,7 @@
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-lambda-java-tests</artifactId>
     <version>1.1.3-SNAPSHOT</version>
+    <!-- lastPublished: 1.1.2 (auto-updated by release.yml) -->
     <packaging>jar</packaging>
 
     <name>AWS Lambda Java Tests</name>