From 14957fada30e658efac182acdde051558e783468 Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 08:49:21 -0500 Subject: [PATCH 1/6] Add documentation releated build and checks to GitHub workflows There's nothing in the pull request verification that checks if the command-line references are up-to-date. Add a job to the pull request update workflow that verifies this. There's nothing in the release build workflow that generates the documentation and uploads the documentation artifacts so that they can be published. Add a step to the build release job that generates the documentation so that it can be published to swift.org. --- .github/workflows/build_release.yml | 11 +++++++++-- .github/workflows/pull_request.yml | 21 +++++++++++++++++++++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_release.yml b/.github/workflows/build_release.yml index c45dd6e4..69ee07e3 100644 --- a/.github/workflows/build_release.yml +++ b/.github/workflows/build_release.yml @@ -23,10 +23,17 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 - - name: Build Artifact + - name: Build Release Artifact run: swift run build-swiftly-release ${{ inputs.skip }} ${{ inputs.version }} - - name: Upload Artifact + - name: Upload Release Artifact uses: actions/upload-artifact@v4 with: path: .build/release/swiftly-*.tar.gz if-no-files-found: error + - name: Build Documentation Artifacts + run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs + - name: Upload Documentation Artifacts + uses: actions/upload-artifact@v4 + with: + path: .build/docs/** + if-no-files-found: error diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index b1554a2c..c348e92e 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -57,3 +57,24 @@ jobs: linux_pre_build_command: ./scripts/prep-gh-action.sh linux_build_command: swift run swiftformat --lint --dryrun . enable_windows_checks: false + + docscheck: + name: Documentation Check + runs-on: ubuntu-latest + container: + image: "swift:6.0-noble" + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Prepare the action + run: ./scripts/prep-gh-action.sh && ./scripts/install-libarchive.sh + - name: Generate Swiftly CLI Reference and Check for Differences + run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git diff-index --quiet HEAD -- || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1) + - name: Generate Documentation Set + run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs + - name: Upload Documentation Artifacts + uses: actions/upload-artifact@v4 + with: + path: .build/docs/** + if-no-files-found: error + retention-days: 1 From bf73dba6f2e78faf57cb59d78b374c43241838b0 Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 09:01:10 -0500 Subject: [PATCH 2/6] Overcome git dubious repo error --- .github/workflows/pull_request.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index c348e92e..225445da 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -69,7 +69,7 @@ jobs: - name: Prepare the action run: ./scripts/prep-gh-action.sh && ./scripts/install-libarchive.sh - name: Generate Swiftly CLI Reference and Check for Differences - run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git diff-index --quiet HEAD -- || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1) + run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git config --global --add safe.directory $(pwd) && git diff-index --quiet HEAD -- || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1) - name: Generate Documentation Set run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs - name: Upload Documentation Artifacts From f2033d4bf3661a0fd6c97977661564bffa8d44df Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 09:10:41 -0500 Subject: [PATCH 3/6] Try git diff to verify if there are local changes to the cli reference --- .github/workflows/pull_request.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index 225445da..25210944 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -69,7 +69,7 @@ jobs: - name: Prepare the action run: ./scripts/prep-gh-action.sh && ./scripts/install-libarchive.sh - name: Generate Swiftly CLI Reference and Check for Differences - run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git config --global --add safe.directory $(pwd) && git diff-index --quiet HEAD -- || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1) + run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git config --global --add safe.directory $(pwd) && git diff --exit-code Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1) - name: Generate Documentation Set run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs - name: Upload Documentation Artifacts From 85510a91936ead4d96b9fc5522ac697636302785 Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 09:23:44 -0500 Subject: [PATCH 4/6] Give the uploaded artifacts unique names to avoid collisions --- .github/workflows/build_release.yml | 2 ++ .github/workflows/pull_request.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/build_release.yml b/.github/workflows/build_release.yml index 69ee07e3..c2639bd8 100644 --- a/.github/workflows/build_release.yml +++ b/.github/workflows/build_release.yml @@ -28,6 +28,7 @@ jobs: - name: Upload Release Artifact uses: actions/upload-artifact@v4 with: + name: swiftly-release-x86_64 path: .build/release/swiftly-*.tar.gz if-no-files-found: error - name: Build Documentation Artifacts @@ -35,5 +36,6 @@ jobs: - name: Upload Documentation Artifacts uses: actions/upload-artifact@v4 with: + name: swiftly-docs path: .build/docs/** if-no-files-found: error diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index 25210944..631636d9 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -43,6 +43,7 @@ jobs: - name: Upload Artifact uses: actions/upload-artifact@v4 with: + name: swiftly-release-x86_64 path: .build/release/swiftly-*.tar.gz if-no-files-found: error retention-days: 1 @@ -75,6 +76,7 @@ jobs: - name: Upload Documentation Artifacts uses: actions/upload-artifact@v4 with: + name: swiftly-docs path: .build/docs/** if-no-files-found: error retention-days: 1 From 4009a8b8a5093e0f23be94a8e86a445c1ff200ab Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 09:29:30 -0500 Subject: [PATCH 5/6] Create an intentional difference in the cli reference documentation for testing purposes --- Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md index fb3591fd..0f9d90b4 100644 --- a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md +++ b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md @@ -1,4 +1,4 @@ -# swiftly +# swiftly From 623b8076fed4e3e1c167fe09089db4b6676f7c3b Mon Sep 17 00:00:00 2001 From: "Chris (SPG) McGee" Date: Thu, 14 Nov 2024 10:12:53 -0500 Subject: [PATCH 6/6] Undo intentional difference to the CLI reference --- Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md index 0f9d90b4..fb3591fd 100644 --- a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md +++ b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md @@ -1,4 +1,4 @@ -# swiftly +# swiftly