From 25c9caa09cddd2f056d8e1c6056fcb9c1081594e Mon Sep 17 00:00:00 2001 From: Miles Petrov Date: Wed, 28 Aug 2024 13:57:00 -0400 Subject: [PATCH] Enable builds and demo pages for forked repos --- .github/workflows/build-docs.yml | 83 ---------------- .github/workflows/demo-build.yml | 143 ++++++++++++++++++++++++++++ .github/workflows/demo-cleanup.yml | 93 ++++++++++++++++++ .github/workflows/demo-pr-links.yml | 26 +++++ .github/workflows/deploy.yml | 80 ---------------- .github/workflows/main.yml | 77 --------------- .github/workflows/pages-cleanup.yml | 50 ---------- docs/.vitepress/config.ts | 2 +- docs/index.md | 2 +- docs/introduction/setup.md | 23 +++++ docs/typedoc-README.md | 2 +- 11 files changed, 288 insertions(+), 293 deletions(-) delete mode 100644 .github/workflows/build-docs.yml create mode 100644 .github/workflows/demo-build.yml create mode 100644 .github/workflows/demo-cleanup.yml create mode 100644 .github/workflows/demo-pr-links.yml delete mode 100644 .github/workflows/deploy.yml delete mode 100644 .github/workflows/main.yml delete mode 100644 .github/workflows/pages-cleanup.yml diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml deleted file mode 100644 index 2ff44466cf2..00000000000 --- a/.github/workflows/build-docs.yml +++ /dev/null @@ -1,83 +0,0 @@ -name: NPM install and build - -on: - workflow_call: - inputs: - cache_sha: - type: string - required: true - -jobs: - install-build: - name: Install and build - runs-on: ubuntu-latest - steps: - - name: Check if contributor is an org member - id: is_organization_member - if: github.event_name == 'pull_request_target' - uses: JamesSingleton/is-organization-member@1.0.1 - with: - organization: ramp4-pcar4 - username: ${{ github.event.pull_request.head.user.login }} - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Output comment and end build if not org member - if: github.event_name == 'pull_request_target' - run: | - result=${{ steps.is_organization_member.outputs.result }} - if [ $result == false ]; then - user=${{ github.event.pull_request.head.user.login }} - echo Either ${user} is not part of the ramp4-pcar4 organization - echo or ${user} has its Organization Visibility set to Private at - echo https://github.com/orgs/ramp4-pcar4/people?query=${user} - exit 1 - fi - - - uses: actions/checkout@v4 - with: - ref: ${{ github.event.pull_request.head.ref || github.ref_name }} - repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }} - - - uses: actions/setup-node@v4 - with: - node-version: '22.5.1' - cache: 'npm' - - - name: Try to restore node_modules folder from cache - id: cache-node-modules - uses: actions/cache@v4 - with: - path: ./node_modules - key: npm-${{ hashFiles('./package-lock.json') }} - - - name: Otherwise install npm dependencies - if: steps.cache-node-modules.outputs.cache-hit != 'true' - run: npm ci - - - name: Persist docsite output for other workflows - uses: actions/cache@v4 - with: - path: 'docs' - key: docs-${{ inputs.cache_sha }} - - - name: Update docsite version references - uses: jacobtomlinson/gha-find-replace@v3 - with: - find: '{{ramp-version}}' - replace: ${{ github.ref_name }} - include: 'docs/**' - regex: false - - - name: Build the ts docs! - run: npm run ts-docs:generate - - - name: Build the vitepress docs! - run: npm run vite-docs:generate - - - name: Consolidate docsite files - run: | - mkdir -p docs - rm -rf docs - mkdir -p docs/api-tech-docs - mv vite-docs/* docs/ - mv ts-docs/* docs/api-tech-docs diff --git a/.github/workflows/demo-build.yml b/.github/workflows/demo-build.yml new file mode 100644 index 00000000000..6bd02136e4f --- /dev/null +++ b/.github/workflows/demo-build.yml @@ -0,0 +1,143 @@ +name: Build demo site and deploy to GitHub Pages + +on: push + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: write + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these deployments to complete. +concurrency: + group: 'pages' + cancel-in-progress: false + +jobs: + build: + name: Build the project + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/checkout@v4 + with: + path: ramp + + - uses: actions/setup-node@v4 + with: + node-version: '22.5.1' + cache: 'npm' + cache-dependency-path: ramp/package-lock.json + + - name: Set up Git + run: | + git config --global user.name "GitHub Action" + git config --global user.email "action@github.com" + + - name: Create demp-page branch (orphan) if it doesn't exist + run: | + # ramp is already checked out in the previous step, use git there to check if demo-pages exists on origin + cd ramp + git fetch origin + + if git show-ref --quiet refs/remotes/origin/demo-page; then + echo "Branch 'demo-page' exists on origin." + else + echo "Branch 'demo-page' does not exist on origin. Creating an orphan branch..." + cd ../ + mkdir -p demo-page + cd demo-page + git init + git checkout --orphan demo-page + git commit --allow-empty -m "Create orphan branch" + git remote add origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository_owner }}/ramp4-pcar4 + git push -u origin demo-page + echo "Orphan branch 'demo-page' has been created and pushed to origin." + cd ../ + # For simplicity we'll delete the demo-page folder now since it'll be checked out in the next step in all cases + rm -rf demo-page + fi + + - uses: actions/checkout@v4 + with: + ref: demo-page + path: demo-page + fetch-depth: 0 + + - name: Remove the old demo if it exists and make docs folder + run: | + rm -rf demo-page/${{ github.ref_name }} + + # this is the deepest folder we need to create + mkdir -p demo-page/${{ github.ref_name }}/docs/api-tech-docs + + # Before building the docs we need to find and replace the version and repo owner references in the raw docs (next two steps). + - name: Update docsite version references before docs are built + uses: jacobtomlinson/gha-find-replace@v3 + with: + find: '{{ramp-version}}' + replace: ${{ github.ref_name }} + include: 'ramp/docs/**' + regex: false + + - name: Update docsite repo owner references before docs are built so that the links point to the correct repo + uses: jacobtomlinson/gha-find-replace@v3 + with: + find: '{{repo-owner}}' + replace: ${{ github.repository_owner }} + include: 'ramp/docs/**' + regex: false + + - name: Build the project and generate docs + run: | + cd ramp + npm ci + npm run build + npm run ts-docs:generate + npm run vite-docs:generate + + - name: Publish to NPM for tag releases on main repo only + if: github.repository == 'ramp4-pcar4/ramp4-pcar4' && startsWith(github.ref, 'refs/tags/v') + run: | + TAG_VERSION=${GITHUB_REF#refs/tags/v} + PACKAGE_VERSION=$(node -p "require('./package.json').version") + if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then + npm version --allow-same-version --no-git-tag-version $TAG_VERSION + fi + + npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Move the built project and docs into the demo-page folder for deployment + run: | + mv ramp/dist/* demo-page/${{ github.ref_name }} + mv ramp/vite-docs/* demo-page/${{ github.ref_name }}/docs + mv ramp/ts-docs/* demo-page/${{ github.ref_name }}/docs/api-tech-docs + + - name: Commit and squash to the demo-page branch + run: | + cd demo-page + git add . + git commit -m "Applied changes from demo-folder to demo-page" + + # Squash the commit history into a single commit + git reset --soft $(git rev-list --max-parents=0 HEAD) + git commit -m "Applied changes from demo-folder to demo-page" + git push origin HEAD --force + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: demo-page + retention-days: 1 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/demo-cleanup.yml b/.github/workflows/demo-cleanup.yml new file mode 100644 index 00000000000..51b3a98b411 --- /dev/null +++ b/.github/workflows/demo-cleanup.yml @@ -0,0 +1,93 @@ +name: Clean up demo folders when they no longer exist + +on: + schedule: + - cron: '0 0 * * *' # Runs every day at midnight + workflow_dispatch: # Allows manual trigger from the GitHub website + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: write + pages: write + id-token: write + +jobs: + clean_folders: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Checkout the repo + uses: actions/checkout@v4 + with: + ref: demo-page + + - name: Set up Git + run: | + git config --global user.name "GitHub Action" + git config --global user.email "action@github.com" + + - name: Fetch remote branches and tags from origin + run: git fetch origin --prune + + - name: Run cleanup script + run: | + # Get all remote branch names from origin + remote_branches=$(git branch -r | grep -v '\->' | grep "origin/" | sed "s# *origin/##g") + + # Get all remote tag names from origin + remote_tags=$(git ls-remote --tags origin | awk -F/ '{print $NF}' | sed 's/\^{}//') + + # Combine branches and tags into a single list + remote_refs=$(echo -e "$remote_branches\n$remote_tags") + + # Get all folder names in the current directory + local_folders=$(ls -d */ | sed 's#/##') + + # Loop through each folder in the current directory + for folder in $local_folders; do + # Check if the folder name exists in the list of remote refs + if ! echo "$remote_refs" | grep -qw "$folder"; then + # If the folder name doesn't exist in the remote refs, delete the folder + echo "Deleting folder: $folder" + rm -rf "$folder" + fi + done + + - name: Commit and push changes + id: commit-changes + run: | + git add . + if ! git diff --cached --exit-code > /dev/null; then + git commit -m "Automated folder cleanup" + + # Squash the commit history into a single commit + git reset --soft $(git rev-list --max-parents=0 HEAD) + git commit -m "Automated folder cleanup" + + git push -f origin demo-page + # Let the next steps know that changes were made and deployment is needed + echo "changes=true" >> $GITHUB_ENV + else + echo "No changes to commit" + # Let the next steps know that no changes were made and deployment will be skipped + echo "changes=false" >> $GITHUB_ENV + fi + + - name: Upload artifact + if: env.changes == 'true' + uses: actions/upload-pages-artifact@v3 + with: + path: '.' + retention-days: 1 + + - name: Setup Pages + if: env.changes == 'true' + uses: actions/configure-pages@v5 + + - name: Deploy to GitHub Pages + if: env.changes == 'true' + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/demo-pr-links.yml b/.github/workflows/demo-pr-links.yml new file mode 100644 index 00000000000..357bae50a22 --- /dev/null +++ b/.github/workflows/demo-pr-links.yml @@ -0,0 +1,26 @@ +name: PR Commenter + +on: + pull_request: + types: [opened] + +jobs: + comment-on-pr: + runs-on: ubuntu-latest + steps: + - name: Comment on the PR + uses: peter-evans/create-or-update-comment@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + issue-number: ${{ github.event.pull_request.number }} + body: | + Your demo site is ready! 🚀 + + Enhanced Testing: + Samples: https://${{github.event.pull_request.user.login}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/enhanced-samples.html + Catalogue: https://${{github.event.pull_request.user.login}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/enhanced-all.html + + Legacy Testing: + Main: https://${{github.event.pull_request.user.login}}.github.io/ramp4-pcar4/${{github.head_ref}}/ + Catalogue: https://${{github.event.pull_request.user.login}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/index-all.html + Samples: https://${{github.event.pull_request.user.login}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/index-samples.html diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index 69d8e699a65..00000000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,80 +0,0 @@ -name: Publish to GitHub pages and NPM - -on: - workflow_call: - inputs: - cache_sha: - type: string - required: true - -jobs: - deploy: - name: Deploy - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: actions/setup-node@v4 - with: - node-version: '22.5.1' - cache: 'npm' - registry-url: 'https://registry.npmjs.org' - - - name: Get dist files - uses: actions/cache@v4 - with: - path: dist - key: dist-${{ inputs.cache_sha }} - - - name: Get docsite files - id: get-docs-cache - uses: actions/cache@v4 - with: - path: docs - key: docs-${{ inputs.cache_sha }} - - - name: Add docs folder to dist - if: steps.get-docs-cache.outputs.cache-hit == 'true' - run: mv docs dist - - - name: Deploy to GitHub Pages 🚀 - uses: JamesIves/github-pages-deploy-action@v4.5.0 - with: - branch: gh-pages - folder: dist - target-folder: ${{ github.head_ref || github.ref_name }} - single-commit: true - - - name: Publish to NPM - if: github.repository == 'ramp4-pcar4/ramp4-pcar4' && startsWith(github.ref, 'refs/tags/v') - run: | - TAG_VERSION=${GITHUB_REF#refs/tags/v} - PACKAGE_VERSION=$(node -p "require('./package.json').version") - if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then - npm version --allow-same-version --no-git-tag-version $TAG_VERSION - fi - - npm publish - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - - uses: actions/github-script@v6 - name: Post link to demo for PR's - if: github.event_name == 'pull_request_target' && github.event.action == 'opened' - with: - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: `Your demo site is ready! 🚀 - - Enhanced Testing: - Samples: https://${{github.repository_owner}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/enhanced-samples.html - Catalogue: https://${{github.repository_owner}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/enhanced-all.html - - Legacy Testing: - Main: https://${{github.repository_owner}}.github.io/ramp4-pcar4/${{github.head_ref}}/ - Catalogue: https://${{github.repository_owner}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/index-all.html - Samples: https://${{github.repository_owner}}.github.io/ramp4-pcar4/${{github.head_ref}}/demos/index-samples.html` - }) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml deleted file mode 100644 index ad46e9f462e..00000000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: Main Build Workflow - -on: - pull_request_target: - types: [opened, synchronize, reopened] - - push: - branches: - - 'main' - - 'qa' - tags: - - v** - -jobs: - docs: - name: Create documentation - if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || startsWith(github.ref, 'refs/tags/v') - uses: ./.github/workflows/build-docs.yml - with: - cache_sha: ${{ format('{0}-{1}', github.ref_name, github.event.pull_request.head.sha || github.sha) }} - - build: - name: Build the project - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - ref: ${{ github.event.pull_request.head.ref || github.ref_name }} - repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }} - - - uses: actions/setup-node@v4 - with: - node-version: '22.5.1' - cache: 'npm' - - - name: Try to restore node_modules folder from cache - id: cache-node-modules - uses: actions/cache@v4 - with: - path: ./node_modules - key: npm-${{ hashFiles('./package-lock.json') }} - - - name: Otherwise install npm dependencies - if: steps.cache-node-modules.outputs.cache-hit != 'true' - run: npm ci - - - name: Update package.json version if necessary - if: startsWith(github.ref, 'refs/tags/v') - run: | - TAG_VERSION=${GITHUB_REF#refs/tags/v} - PACKAGE_VERSION=$(node -p "require('./package.json').version") - if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then - npm version --allow-same-version --no-git-tag-version $TAG_VERSION - echo "::warning::Tag version ($TAG_VERSION) did not match package.json version ($PACKAGE_VERSION). Updated package.json to $TAG_VERSION." - else - echo "::info::Tag version ($TAG_VERSION) matches package.json version ($PACKAGE_VERSION)." - fi - - - name: Build the files! - run: npm run build - env: - NODE_OPTIONS: '--max-old-space-size=8192' - - - name: Cache dist files - uses: actions/cache@v4 - with: - path: dist - key: dist-${{ format('{0}-{1}', github.ref_name, github.event.pull_request.head.sha || github.sha) }} - - deploy-pages: - needs: [docs, build] - if: ${{ always() && needs.build.result == 'success' }} - name: Deploy the files - uses: ./.github/workflows/deploy.yml - with: - cache_sha: ${{ format('{0}-{1}', github.ref_name, github.event.pull_request.head.sha || github.sha) }} - secrets: inherit diff --git a/.github/workflows/pages-cleanup.yml b/.github/workflows/pages-cleanup.yml deleted file mode 100644 index 643acc0c1a4..00000000000 --- a/.github/workflows/pages-cleanup.yml +++ /dev/null @@ -1,50 +0,0 @@ -name: Cleanup GitHub pages - -on: - pull_request_target: - types: [closed] - -jobs: - cleanup-pages: - name: Cleanup GitHub pages - runs-on: ubuntu-latest - steps: - - name: Check if contributor is an org member - id: is_organization_member - if: github.event_name == 'pull_request_target' - uses: JamesSingleton/is-organization-member@1.0.1 - with: - organization: ramp4-pcar4 - username: ${{ github.event.pull_request.head.user.login }} - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Output comment and end build if not org member - if: github.event_name == 'pull_request_target' - run: | - result=${{ steps.is_organization_member.outputs.result }} - if [ $result == false ]; then - user=${{ github.event.pull_request.head.user.login }} - echo Either ${user} is not part of the ramp4-pcar4 organization - echo or ${user} has its Organization Visibility set to Private at - echo https://github.com/orgs/ramp4-pcar4/people?query=${user} - exit 1 - fi - - ## Delete the PR demo from gh-pages when the PR is closed - - uses: actions/checkout@v4 - with: - ref: 'gh-pages' - - - name: Delete the files - shell: bash - run: | - git config --global user.email "miles.petrov@ec.gc.ca" - git config --global user.name "Miles Petrov" - git pull --ff-only origin gh-pages - if [ -d "${{ github.head_ref }}" ]; then - git rm -r "${{ github.head_ref }}/*" || true - else - echo "Directory ${{ github.head_ref }} does not exist or contains invalid characters." - fi - git commit -a -m 'Delete PR demo ${{ github.head_ref }}' - git push -f origin HEAD:gh-pages diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 8078c8152d2..1706746be2b 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -29,7 +29,7 @@ export default { }, { text: 'API Reference', - link: 'https://ramp4-pcar4.github.io/ramp4-pcar4/{{ramp-version}}/docs/api-tech-docs/index.html' + link: 'https://{{repo-owner}}.github.io/ramp4-pcar4/{{ramp-version}}/docs/api-tech-docs/index.html' }, { text: 'Releases', diff --git a/docs/index.md b/docs/index.md index 83630274ae4..31cd570869e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,7 @@ hero: link: overview - theme: alt text: API Reference - link: https://ramp4-pcar4.github.io/ramp4-pcar4/{{ramp-version}}/docs/api-tech-docs/index.html + link: https://{{repo-owner}}.github.io/ramp4-pcar4/{{ramp-version}}/docs/api-tech-docs/index.html - theme: alt text: GitHub link: https://github.com/ramp4-pcar4/ramp4-pcar4 diff --git a/docs/introduction/setup.md b/docs/introduction/setup.md index 93f78908f9d..fb003370472 100644 --- a/docs/introduction/setup.md +++ b/docs/introduction/setup.md @@ -1,3 +1,26 @@ +# Demo Setup for Forked Repos + +When you push changes to your forked repo, a demo preview is automatically generated. The demo preview will update each time you push changes. Note that demos are deleted daily whenever the source branch or tag is deleted from your forked repo. + +### Accessing Your Demo Previews: +- **Branch or Tag Preview**: Visit `https://{{github-username}}.github.io/ramp4-pcar4/{{branch-or-tag-name}}` to see a live preview of the branch or tag you've pushed. +- **List of All Demos**: View all your demo previews by navigating to `https://github.com/{{github-username}}/ramp4-pcar4/tree/demo-page`. + +### Enabling Demos for Your Forked Repo: +To enable demo previews on your forked repository, update the following settings: + +1. **GitHub Pages**: + - Go to `Settings -> Pages -> Build and deployment source` and select **GitHub Actions**. + +2. **Deployment Branches and Tags**: + - Navigate to `Settings -> Environments -> github-pages -> Deployment branches and tags` and choose **No restriction**. + +3. **Actions Permissions**: + - Under `Settings -> Actions -> General -> Actions permissions`, set it to **Allow all actions and reusable workflows**. + +4. **Workflow Permissions**: + - Go to `Settings -> Actions -> General -> Workflow permissions`, and select **Read and write permissions**. + # Local development ## Project Setup diff --git a/docs/typedoc-README.md b/docs/typedoc-README.md index 2786a8f4c6b..b55ffd748e4 100644 --- a/docs/typedoc-README.md +++ b/docs/typedoc-README.md @@ -2,4 +2,4 @@

-This site serves as the technical documentation of RAMP 4's TypeScript codebase. For general documentation, please visit the [main documentation site](https://ramp4-pcar4.github.io/ramp4-pcar4/{{ramp-version}}/docs/). +This site serves as the technical documentation of RAMP 4's TypeScript codebase. For general documentation, please visit the [main documentation site](https://{{repo-owner}}.github.io/ramp4-pcar4/{{ramp-version}}/docs/).