jamesfredley commented on code in PR #16486: URL: https://github.com/apache/grails-core/pull/16486#discussion_r4174531550
########## RELEASE.md: ########## @@ -339,8 +380,14 @@ The bundle is `grails-forge-web-netty/build/distributions/grails-forge-web-netty ### Publish `grails-core` documentation -Open the release workflow in `grails-core` and approve the `Publish Documentation` step. Wait until finished, and a -workflow should eventually kick off in `grails-doc` to publish to https://github.com/apache/grails-website/tree/asf-site-production/docs and https://grails.apache.org/docs/. +Open the release workflow in `grails-core` and approve the `Publish Documentation` step. The step does not rebuild the +documentation. It downloads the voted `apache-grails-<version>-docs.zip` from dist.apache.org, verifies its checksum and +signature, and publishes the extracted `html` folder to https://github.com/apache/grails-website/tree/asf-site-production/docs, +which serves https://grails.apache.org/docs/. It takes the zip from the `release` area once the distributions have been +moved, and from the `dev` area until then. + +To correct the documentation of a version that is already released, run the `Release - Publish Documentation` workflow Review Comment: This correction path still rebuilds, and it can publish the wrong version. `Release - Publish Documentation` (`.github/workflows/release-publish-docs.yml:71`) runs `./gradlew grails-doc:build -PgithubBranch=...` and does not set the Gradle project version. `VERSION` only steers the deploy action. A run from current `8.0.x` builds `8.0.0-SNAPSHOT` documentation and can publish it under the requested release version, including the wrong headings and version-dependent links. Do not document this workflow as a safe correction until it refuses to deploy unless the built version equals the requested version. Build corrections from the intended release sources with the version aligned, and keep that route distinct from publishing the voted zip. ########## .github/workflows/release.yml: ########## @@ -594,33 +640,36 @@ jobs: sudo rm -rf /opt/hostedtoolcache/CodeQL df -h - - name: "📥 Checkout repository" - uses: actions/[email protected] - with: - fetch-depth: 0 # needed for docs release dropdown, (fetch-tags: true with fetch-depth: 1 does not work; https://github.com/actions/checkout/issues/1471) - filter: tree:0 # limit size, keeping tags for docs release dropdown - token: ${{ secrets.GITHUB_TOKEN }} - ref: ${{ env.TAG }} - - name: "📅 Ensure Common Build Date" # to ensure a reproducible build - run: echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> "$GITHUB_ENV" - - name: "☕️ Setup JDK" - uses: actions/[email protected] - with: - distribution: ${{ env.JAVA_DISTRIBUTION }} - java-version: ${{ env.JAVA_VERSION }} - - name: "🐘 Setup Gradle" - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb # v6.3.0 - with: - cache-provider: basic # 'basic' uses the MIT-licensed, open-source cache provider; the default 'enhanced' provider (v6+) is proprietary (Gradle commercial Terms of Use) - develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }} - - name: "📖 Generate Documentation" - run: ./gradlew grails-doc:build -PgithubBranch=${TARGET_BRANCH} + - name: "📥 Download the voted documentation distribution" + # The vote approved this exact ZIP, so it is published as-is instead of rebuilt. It is in + # the release area once releaseDistributions.sh has promoted it, and in dev until then. + run: | + DOCS_ZIP="${DIST_NAME}-${VERSION}-docs.zip" + for area in release dev; do + base_url="https://dist.apache.org/repos/dist/${area}/${SVN_PROJECT}/${SVN_FOLDER}/${VERSION}/distribution"; + if curl -f -s -L -O "${base_url}/${DOCS_ZIP}"; then + curl -f -L -O "${base_url}/${DOCS_ZIP}.sha512" + curl -f -L -O "${base_url}/${DOCS_ZIP}.asc" + echo "Downloaded ${DOCS_ZIP} from ${base_url}" + exit 0 + fi + done + echo "❌ ${DOCS_ZIP} was found in neither the release nor the dev distribution area" >&2 + exit 1 + - name: "🔐 Verify the documentation distribution" + run: | + sha512sum -c "${DIST_NAME}-${VERSION}-docs.zip.sha512" + export GNUPGHOME="$(mktemp -d)" + curl -f -L "https://dist.apache.org/repos/dist/release/${SVN_PROJECT}/KEYS"; | gpg --batch --import + gpg --batch --verify "${DIST_NAME}-${VERSION}-docs.zip.asc" "${DIST_NAME}-${VERSION}-docs.zip" + - name: "📦 Extract the documentation distribution" + run: unzip -q "${DIST_NAME}-${VERSION}-docs.zip" - name: "🚀 Publish to GitHub Pages" uses: apache/grails-github-actions/deploy-github-pages@asf env: GH_TOKEN: ${{ secrets.GRAILS_GHTOKEN }} # To be able to push to grails-website repo GRADLE_PUBLISH_RELEASE: 'true' - SOURCE_FOLDER: grails-doc/build/docs + SOURCE_FOLDER: ${{ env.DIST_NAME }}-${{ env.VERSION }}-docs/html Review Comment: The voted zip places `LICENSE`, `NOTICE`, and `licenses/` beside `html/` (`grails-doc/build.gradle:769`). This step copies only `SOURCE_FOLDER`, which is now the `html/` directory, so the site redistributes the bundled MIT stylesheets and OFL fonts without those license texts. The stylesheet headers link to a license rather than including the full terms, and the bundled Font Awesome SVG has empty metadata. The zip itself is licensed correctly. Deploy the voted legal files alongside the HTML, with the `licenses/` references still resolving, or include an equivalent legal set in the website payload before the vote. ########## .github/scripts/setReleasedGrailsVersion.sh: ########## @@ -24,4 +24,11 @@ set -e echo "Setting new version in GrailsUtilsTests.java: ${RELEASE_VERSION}" sed -i "s/assertEquals(\".*$/assertEquals(\"${RELEASE_VERSION}\", GrailsUtil.getGrailsVersion());/" "${GITHUB_WORKSPACE}/grails-core/src/test/groovy/grails/util/GrailsUtilTests.java" sed -n "/assertEquals(\".*/p" "${GITHUB_WORKSPACE}/grails-core/src/test/groovy/grails/util/GrailsUtilTests.java" -git add "${GITHUB_WORKSPACE}/grails-core/src/test/groovy/grails/util/GrailsUtilTests.java" \ No newline at end of file +git add "${GITHUB_WORKSPACE}/grails-core/src/test/groovy/grails/util/GrailsUtilTests.java" + +# The documentation links each page to its source on this branch. Record the branch in the +# release commit so a build from the source distribution renders the same links. +echo "Setting githubBranch in gradle.properties: ${TARGET_BRANCH:?TARGET_BRANCH must be set}" +sed -i "s/^githubBranch=.*$/githubBranch=${TARGET_BRANCH}/" "${GITHUB_WORKSPACE}/gradle.properties" Review Comment: Non-blocking. The `/` delimiter fails for a valid branch that contains `/` (`sed: unknown option to 's'`), and `set -e` then aborts the pre-release step. If `githubBranch=` is missing or formatted differently, the substitution matches nothing and the step still succeeds. Current `githubBranch=8.0.x` works, so the ordinary release path is fine. Use a delimiter that cannot appear in a branch name, and fail if the resulting value is not `TARGET_BRANCH`. ########## grails-doc/build.gradle: ########## @@ -757,8 +763,18 @@ docsTask.configure { Sync it -> } tasks.register('dist', Zip).configure { Zip it -> - it.dependsOn(docsTask) - it.from(outputDir) + it.archiveBaseName = 'apache-grails' + it.archiveClassifier = 'docs' + it.into("apache-grails-${project.version}-docs") { CopySpec distribution -> + distribution.from(project.layout.projectDirectory.dir('distribution-artifacts')) { CopySpec legal -> + legal.filesMatching('NOTICE') { FileCopyDetails notice -> Review Comment: Non-blocking. The `NOTICE` year comes from `rootProject.ext.buildDate.year`, but that value is not registered as a task input. An existing checkout that rebuilds the same documentation with a `SOURCE_DATE_EPOCH` from a different year can leave `dist` UP-TO-DATE and keep the previous year. A clean release runner and a fresh source extract do not hit this. Register the year with `inputs.property`, the same way other expanded filter inputs are declared. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
