diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml deleted file mode 100644 index c1ec213..0000000 --- a/.github/workflows/site.yml +++ /dev/null @@ -1,163 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -name: Publish Site - -on: - workflow_call: - inputs: - multi-module: - description: 'Stage the site before publishing. Required for reactors with modules.' - required: false - default: false - type: boolean - - dry-run: - description: 'Build and check out gh-pages, but do not commit or push.' - required: false - default: false - type: boolean - - publish-branch: - description: 'Branch the built site is committed to. gh-pages for project sites; master for the organisation page.' - required: false - default: 'gh-pages' - type: string - - maven_args: - description: 'Goals and arguments used to build the site' - required: false - default: '--batch-mode --errors --show-version -Preporting clean verify' - type: string - - maven-version: - description: 'The Maven version used to build the site' - required: false - default: '3.9.11' - type: string - - jdk-version: - description: 'JDK used to build the site' - required: false - default: '21' - type: string - - jdk-distribution: - description: 'JDK distribution used to build the site' - required: false - default: 'temurin' - type: string - -# one publish at a time: two concurrent runs would race on gh-pages -concurrency: - group: publish-site-${{ github.repository }} - cancel-in-progress: false - -jobs: - publish-site: - name: Publish Site - - if: github.repository_owner == 'codehaus-plexus' - - runs-on: ubuntu-latest - - permissions: - # maven-scm-publish-plugin commits the generated site to the gh-pages branch - contents: write - - steps: - - name: Checkout - uses: actions/checkout@v7 - with: - persist-credentials: false - - - name: Set up JDK - uses: actions/setup-java@v5 - with: - java-version: ${{ inputs.jdk-version }} - distribution: ${{ inputs.jdk-distribution }} - cache: 'maven' - - - name: Set up Maven - run: mvn --errors --batch-mode --show-version org.apache.maven.plugins:maven-wrapper-plugin:3.2.0:wrapper "-Dtype=only-script" "-Dmaven=${{ inputs.maven-version }}" - - - name: Build site - run: ./mvnw ${{ inputs.maven_args }} ${{ inputs.multi-module && 'site site:stage' || 'site' }} - - - name: Publish site - # maven-scm-publish-plugin is not used to do the push here. The POMs configure - # its pubScmUrl explicitly, which means an explicitly configured value always - # wins over the -Dscmpublish.pubScmUrl user property, so the ssh URL from - # scm.developerConnection cannot be overridden from the command line - and ssh - # cannot authenticate with the job token. Pushing with git directly keeps the - # whole step under the workflow's control. - env: - GH_TOKEN: ${{ github.token }} - BRANCH: ${{ inputs.publish-branch }} - DRY_RUN: ${{ inputs.dry-run }} - CONTENT: ${{ inputs.multi-module && 'target/staging' || 'target/site' }} - run: | - set -euo pipefail - - if [ ! -d "$CONTENT" ]; then - echo "::error::the site build produced no $CONTENT directory" - exit 1 - fi - - remote="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - - if git ls-remote --exit-code --heads "$remote" "$BRANCH" >/dev/null 2>&1; then - git clone --branch "$BRANCH" --depth 1 --quiet "$remote" .site-publish - else - echo "branch $BRANCH does not exist yet; creating it" - git clone --depth 1 --quiet "$remote" .site-publish - git -C .site-publish checkout --orphan "$BRANCH" - git -C .site-publish rm -rq --cached . || true - find .site-publish -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} + - fi - - # mirror the built site over the branch content, so pages deleted upstream - # also disappear from the published site - rsync -a --delete --exclude '.git' "$CONTENT"/ .site-publish/ - - cd .site-publish - git config user.name "github-actions[bot]" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add -A - - if git diff --cached --quiet; then - echo "site is unchanged; nothing to publish" - exit 0 - fi - - # sed rather than head: head exits after 50 lines, which SIGPIPEs git status, - # and under `set -o pipefail` that aborts the whole step with exit 141 - changed=$(git diff --cached --name-only | wc -l) - git status --short | sed -n '1,50p' - if [ "$changed" -gt 50 ]; then - echo "... and $((changed - 50)) more" - fi - echo "$changed file(s) changed" - - if [ "$DRY_RUN" = "true" ]; then - echo "::notice::dry run - not committing or pushing" - exit 0 - fi - - git commit -qm "Site checkin for ${GITHUB_REPOSITORY}@${GITHUB_SHA}" - git push --quiet origin "$BRANCH" - echo "::notice::published to $BRANCH" diff --git a/RELEASING.md b/RELEASING.md index dd81903..5c9fc87 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -66,18 +66,9 @@ That covers modello, plexus-compiler, plexus-languages and plexus-interactivity. The `-Preporting` profile is what adds the Javadoc, JXR and surefire reports. Without it you publish a site with no API documentation, which is worse than not republishing at all. -## Publishing from GitHub Actions - -Every project has a **Publish Site** workflow, run from the Actions tab. It does the same thing as the commands above, so you do not need a local checkout or credentials: - -- **multi-module** — set by the caller workflow, not by you -- **dry-run** — builds the site and checks out `gh-pages` without committing. Worth using the first time you publish a given project. - -The job token pushes to that repository's own `gh-pages`; there is no secret to configure. - -### Why it isn't automatic - -The workflow is triggered by hand rather than on release. Publishing puts content live with no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that we would rather a person saw the output before it goes up. +Sites are published from a local checkout. There is no workflow for it: publishing puts content live with +no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that +the person doing it should see the output first. ## Snapshot deployment