This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-parent.git
commit 20e23163e8047e1e460c0b9c1a858c52dc3b60fe Author: Volkan Yazıcı <[email protected]> AuthorDate: Fri Apr 12 09:45:15 2024 +0200 Use dedicated website for release branches --- .github/generate-email.sh | 12 +-- .github/workflows/build.yaml | 31 +++++++- .github/workflows/deploy-release-reusable.yaml | 88 +++------------------- .../ROOT/pages/release-instructions-project.adoc | 15 +++- src/site/antora/modules/ROOT/pages/usage.adoc | 86 +++++++++++++++------ 5 files changed, 124 insertions(+), 108 deletions(-) diff --git a/.github/generate-email.sh b/.github/generate-email.sh index 77e25a2..5fd4bda 100755 --- a/.github/generate-email.sh +++ b/.github/generate-email.sh @@ -69,15 +69,15 @@ case $1 in vote) cat <<EOF To: [email protected] -Title: [VOTE][LAZY] Release $PROJECT_NAME $PROJECT_VERSION +Title: [VOTE][LAZY] Release $PROJECT_NAME \`$PROJECT_VERSION\` -This is a lazy-vote to release the $PROJECT_NAME $PROJECT_VERSION. +This is a lazy-vote to release the $PROJECT_NAME \`$PROJECT_VERSION\`. -Website: $PROJECT_STAGING_SITE +Website: $PROJECT_STAGING_SITE-$PROJECT_VERSION GitHub: $PROJECT_REPO Commit: $COMMIT_ID Distribution: $PROJECT_DIST_DIR -Nexus: https://repository.apache.org/content/repositories/orgapachelogging-1113 +Nexus: https://repository.apache.org/content/repositories/orgapachelogging-<FIXME> Signing key: 0x077e8893a6dcc33dd4a4d5b256e73ba9a0b592d0 Please download, test, and cast your votes on this mailing list. @@ -106,9 +106,9 @@ EOF announce) cat <<EOF To: [email protected] -Title: [ANNOUNCE] $PROJECT_NAME $PROJECT_VERSION released +Title: [ANNOUNCE] $PROJECT_NAME \`$PROJECT_VERSION\` released -${PROJECT_NAME} team is pleased to announce the $PROJECT_VERSION +${PROJECT_NAME} team is pleased to announce the \`$PROJECT_VERSION\` release. This project contains the parent POM for other Maven-based Apache Logging Services projects. For further information (support, download, etc.) see the project website[1]. diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 0be2b40..5209398 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -23,12 +23,10 @@ on: - "main" - "release/*" paths-ignore: - - "**.adoc" - "**.md" - "**.txt" pull_request: paths-ignore: - - "**.adoc" - "**.md" - "**.txt" @@ -73,3 +71,32 @@ jobs: contents: write with: project-id: logging-parent + + export-release-version: + needs: deploy-release + runs-on: ubuntu-latest + outputs: + version: ${{ steps.export-version.outputs.version }} + steps: + - name: Export version + id: export-version + run: | + version=$(echo "${{ github.ref_name }}" | sed 's/^release\///') + echo "version=$result" >> "$GITHUB_OUTPUT" + + deploy-release-site: + needs: export-release-version + uses: apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main + # Secrets for committing the generated site + secrets: + GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }} + # Write permissions for committing the generated site + permissions: + contents: write + with: + asf-yaml-content: | + staging: + profile: ~ + whoami: ${{ github.ref_name }}-site-stg-out + subdir: content/logging-parent-${{ needs.export-release-version.outputs.version }} + target-branch: ${{ github.ref_name }}-site-stg-out diff --git a/.github/workflows/deploy-release-reusable.yaml b/.github/workflows/deploy-release-reusable.yaml index 2f6b156..022868c 100644 --- a/.github/workflows/deploy-release-reusable.yaml +++ b/.github/workflows/deploy-release-reusable.yaml @@ -28,14 +28,6 @@ on: description: Identifier used in the distribution artifact and Subversion repository folder filenames (e.g., `logging-parent`) required: true type: string - distribution-attachment-filepath-pattern: - description: The regex pattern matched against the full filepath for determining attachments to be included in the distribution - default: "" - type: string - distribution-attachment-count: - description: The number of attachments expected to be found - default: 0 - type: number secrets: GPG_SECRET_KEY: description: GPG secret key for signing artifacts @@ -141,51 +133,6 @@ jobs: git push -f origin fi - # Node.js cache is needed for Antora - - name: Set up Node.js cache - id: nodejs-cache - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # 4.0.2 - with: - # We should be calculating the cache key using `package-lock.json` instead! - # See https://stackoverflow.com/a/48524475/1278899 - # For that, `package-lock.json` needs to be committed into the repository – right now it is `.gitignore`d. - # Once it is there, we should ideally switch from `npm i` to `npm ci`. - # For that, we need to configure `dependabot` to update hundreds of dependencies listed in `package-lock.json`. - # That translates to a never ending rain of `dependabot` PRs. - # I doubt if the wasted CPU cycles worth the gain. - key: ${{ runner.os }}-nodejs-cache-${{ hashFiles('node', 'node_modules') }} - # `actions/cache` doesn't recommend caching `node_modules`. - # Though none of its recipes fit our bill, since we install Node.js using `frontend-maven-plugin`. - # See https://github.com/actions/cache/blob/main/examples.md#node---npm - # We settle for this quick-n-dirty solution for the time being. - path: | - node - node_modules - - - name: Build the website - shell: bash - env: - # Making Node.js cache hit visible for debugging purposes - NODEJS_CACHE_HIT: ${{ steps.nodejs-cache.outputs.cache-hit }} - run: | - export TIMESTAMP=$(./mvnw \ - --non-recursive --quiet --batch-mode \ - -DforceStdout=true \ - -Dexpression=project.build.outputTimestamp \ - help:evaluate \ - | tail -n 1) - ./mvnw \ - --show-version --batch-mode --errors --no-transfer-progress \ - -Dmaven.test.skip \ - install - ./mvnw \ - --show-version --batch-mode --errors --no-transfer-progress \ - site - cd target/site - find . -empty -type d -delete - find . -print0 | xargs -0 touch -d "$TIMESTAMP" - find . -print0 | sort --zero-terminated | xargs -0 zip -oX ../site.zip - - name: Upload to Nexus shell: bash env: @@ -201,29 +148,21 @@ jobs: - name: Stage distribution attachments shell: bash - env: - DIST_ATTACHMENT_FILEPATH_PATTERN: ${{ inputs.distribution-attachment-filepath-pattern }} - DIST_ATTACHMENT_COUNT: ${{ inputs.distribution-attachment-count }} run: | - # Determine the distribution attachment filepath pattern, if none provided - if [[ -z "$DIST_ATTACHMENT_FILEPATH_PATTERN" ]]; then - - # Dump deployed artifacts to a local folder - export ALT_DEPLOYMENT_REPO_FILEPATH="target/alt-deployment-repo" - mkdir "$ALT_DEPLOYMENT_REPO_FILEPATH" - ./mvnw \ - --show-version --batch-mode --errors --no-transfer-progress \ - -DaltDeploymentRepository=apache.releases.https::file:"$ALT_DEPLOYMENT_REPO_FILEPATH" \ - -Dsign.skip \ - -P deploy + # Dump deployed artifacts to a local folder + export ALT_DEPLOYMENT_REPO_FILEPATH="target/alt-deployment-repo" + mkdir "$ALT_DEPLOYMENT_REPO_FILEPATH" + ./mvnw \ + --show-version --batch-mode --errors --no-transfer-progress \ + -DaltDeploymentRepository=apache.releases.https::file:"$ALT_DEPLOYMENT_REPO_FILEPATH" \ + -Dsign.skip \ + -P deploy - # This regex needs to work for both Java (`distribution` profile) and `find` (while counting attachments)! - # Hence, we don't escape dots, etc. with backslashes, which is problematic to get working in both worlds. - export DIST_ATTACHMENT_FILEPATH_PATTERN="^$ALT_DEPLOYMENT_REPO_FILEPATH/.+-$PROJECT_VERSION"'((-tests)?.jar|-cyclonedx.xml)$' - export DIST_ATTACHMENT_COUNT=$(find "$ALT_DEPLOYMENT_REPO_FILEPATH" -type f -regextype posix-extended -regex "$DIST_ATTACHMENT_FILEPATH_PATTERN" | wc -l) - - fi + # This regex needs to work for both Java (`distribution` profile) and `find` (while counting attachments)! + # Hence, we don't escape dots, etc. with backslashes, which is problematic to get working in both worlds. + export DIST_ATTACHMENT_FILEPATH_PATTERN="^$ALT_DEPLOYMENT_REPO_FILEPATH/.+-$PROJECT_VERSION"'((-tests)?.jar|-cyclonedx.xml)$' + export DIST_ATTACHMENT_COUNT=$(find "$ALT_DEPLOYMENT_REPO_FILEPATH" -type f -regextype posix-extended -regex "$DIST_ATTACHMENT_FILEPATH_PATTERN" | wc -l) # Pass the necessary environment variables cat >> $GITHUB_ENV << EOF @@ -303,9 +242,6 @@ jobs: > "${DIST_FILENAME_VERSIONED_PREFIX}-email-${EMAIL_TYPE}.txt" done - # Copy the site - cp "$GITHUB_WORKSPACE/target/site.zip" "${DIST_FILENAME_VERSIONED_PREFIX}-site.zip" - # Copy the distribution cp "$DIST_FILEPATH_PREFIX"* . diff --git a/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc b/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc index 9f7c6d4..9c58ecc 100644 --- a/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc +++ b/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc @@ -53,7 +53,12 @@ git checkout -B release/7.8.0 origin/main If your project refers to its own version in the site sources, those need to be updated too. For instance, `site-project.version` needs to be updated for `logging-parent`. ==== -.. Release the changelog: `./mvnw -N changelog-release` +.. Release the changelog: ++ +[source,bash] +---- +./mvnw -N changelog-release +---- .. Edit the release notes (i.e., `src/changelog/7.8.0/.release-notes.adoc.ftl`) . Commit & push your changes: @@ -74,7 +79,7 @@ You can iterate on the `release/7.8.0` branch to perfect it. .. The `project.build.outputTimestamp` property in `pom.xml` is updated .. *Signed artifacts* are uploaded to the _Staging Repositories_ in https://repository.apache.org/[repository.apache.org] .. *Signed distribution and its checksum* (e.g., `apache-{project-id}-7.8.0-{bin,src}.{zip,.zip.asc,.zip.sha512}`) are uploaded to https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}/7.8.0] Subversion repository (along with auxiliary files; website, email texts, etc.) -.. {site-url-staging}[The project **staging** website] is deployed +.. {site-url-staging}-7.8.0[The release staging website] is deployed using the freshly populated `release/7.8.0-site-stg-out` branch + If not, commit necessary fixes, push, and repeat. @@ -151,6 +156,12 @@ git merge rel/7.8.0 # Pull changes up to the newly created tag git branch -D release/7.8.0 git push --delete origin release/7.8.0 ---- +. Delete the release staging website branch: ++ +[source,bash] +---- +git push --delete origin release/7.8.0-site-stg-out +---- [#publish-release-asf] === In the ASF infrastructure diff --git a/src/site/antora/modules/ROOT/pages/usage.adoc b/src/site/antora/modules/ROOT/pages/usage.adoc index a8e51e9..ca7730c 100644 --- a/src/site/antora/modules/ROOT/pages/usage.adoc +++ b/src/site/antora/modules/ROOT/pages/usage.adoc @@ -40,36 +40,78 @@ You can use {project-name} as follows: == Website deployment Using `deploy-site-reusable.yaml` reusable GitHub Actions workflow, you can automate the website deployments for staging and production environments. -See how {project-github-url}/blob/main/.github/workflows/deploy-site.yaml[`deploy-site.yaml` of {project-name}] achieves that using the following repository branching scheme: +See how {project-github-url}/blob/main/.github/workflows/deploy.yaml[`deploy.yaml`] and {project-github-url}/blob/main/.github/workflows/deploy-site.yaml[`deploy-site.yaml`] of {project-name} achieves that using the following repository branching scheme: -`main`:: -Contains the _sources_ (i.e., AsciiDoc files) to build {site-url-staging}[the staging website]. +Staging website:: {site-url-staging}[] -`main-site-stg-out`:: -It is populated automatically by the workflow triggered for changes on `main`. -It contains the _contents_ (i.e., HTML files) of the {site-url-staging}[the staging website]. -In a nutshell, CI builds `main` and copies the generated `target/site` to `main-site-stg-out`. +Production website:: {site-url}[] -`main-site-pro`:: -Contains the _sources_ (i.e., AsciiDoc files) to build the {site-url}[the production website]. +Release staging website:: {site-url-staging}-<version>[] + +Branch `main`:: +Contains the _sources_ (i.e., AsciiDoc files) to build _the staging website_. + +Branch `main-site-stg-out`:: +Populated automatically by the workflow triggered for changes on `main`. +It contains the _contents_ (i.e., HTML files) of the _the staging website_. +In short, CI builds `main` and copies the generated `target/site` to `main-site-stg-out`. + +Branch `main-site-pro`:: +Contains the _sources_ (i.e., AsciiDoc files) to build the _the production website_. It is _manually populated_ by maintainers. For instance, ** after a release, the release tag is merged to `main-site-pro` ** when there are minor website fixes in `main` that can also go to the production website, they are ``cherry-pick``ed onto the `main-site-pro` ** when there are production-only website fixes, they are committed to `main-site-pro` -`main-site-pro-out`:: -It is populated automatically by the workflow triggered for changes on `main-site-pro`. -It contains the _contents_ (i.e., HTML files) of the {site-url}[the production website]. -In a nutshell, CI builds `main-site-pro` and copies the generated `target/site` to `main-site-pro-out`. +Branch `main-site-pro-out`:: +Populated automatically by the workflow triggered for changes on `main-site-pro`. +It contains the _contents_ (i.e., HTML files) of _the production website_. +In short, CI builds `main-site-pro` and copies the generated `target/site` to `main-site-pro-out`. + +Branch `release/<version>`:: +Contains the _sources_ (i.e., AsciiDoc files) to build _the release staging website_. +It is _manually populated_ by the release manager during a release. + +Branch `release/<version>-site-stg-out`:: +Populated automatically by the workflow triggered for changes on `release/<version>`. +It contains the _contents_ (i.e., HTML files) of _the release staging website_. +In short, CI builds `release/<version>` and copies the generated `target/site` to `release/<version>-site-stg-out`. + +Note that this branching scheme allows to + +* host multiple websites in a single repository +* deploy staging websites of multiple releases in parallel -Note that this branching scheme allows to host multiple websites in a repository. For instance, the following branching scheme is used for the Log4j project: -`2.x`:: Log4j 2 staging website sources -`2.x-site-stg-out`:: Log4j 2 staging website contents -`2.x-site-pro`:: Log4j 2 production website sources -`2.x-site-pro-out`:: Log4j 2 production website contents -`main`:: Log4j 3 staging website sources -`main-site-stg-out`:: Log4j 3 staging website contents -`main-site-pro`:: Log4j 3 production website sources -`main-site-pro-out`:: Log4j 3 production website contents +.Log4j branching scheme for website deployments +[cols="7,4m,4m"] +|=== +.2+^.^h|Description +2+^h|Branch name + +^h|Log4j 2 +^h|Log4j 3 + +|Staging website sources +|2.x +|main + +|Staging website contents +|2.x-site-stg-out +|main-site-stg-out + +|Production website sources +|2.x-site-pro +|main-site-pro + +|Production website contents +|2.x-site-pro-out +|main-site-pro-out + +|Release staging website sources +2+|release/<version> + +|Release staging website contents +2+|release/<version>-site-stg-out +|===
