-
Notifications
You must be signed in to change notification settings - Fork 5
docs: sync certified-assets docs and make static-site the primary frontend path #397
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
17 commits
Select commit
Hold shift + click to select a range
5f7e3a4
feat: sync certified-assets docs into Frontends
marc0olo 28b8182
docs: make static-site the primary frontend path
marc0olo 22e706b
docs: name frontend hosting by the goal, not by the tool
marc0olo 6ed3cc8
docs: put frontend links on the right term and the right target
marc0olo 8fc65f4
chore: sync static-site docs to dfinity/certified-assets 65c0f32
marc0olo 4bb3c85
docs: point the frontend entry points at the static site path
marc0olo e633f50
docs: drop the removed photo-storage example and stop presenting prog…
marc0olo 21dbbac
infra: check heading anchors, and make the sync fail without writing
marc0olo 8b4e346
docs: call it the frontend canister where the role is what matters
marc0olo 22eb5e1
docs: settle the three names, and admit the SNS exception
marc0olo 9c934e3
docs: link the canister name to its repo
marc0olo a3fbf4d
docs: note that the Frontends sidebar group lists its pages explicitly
marc0olo c081394
fix: address Copilot review on the static-site sync
marc0olo 38366ba
fix: address the second Copilot review on the static-site sync
marc0olo 72601ca
fix: address the third Copilot review on the static-site sync
marc0olo 32b9bd4
fix: address the fourth Copilot review, ours only
marc0olo 1343a13
fix: address the fifth Copilot review, ours only
marc0olo File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,194 @@ | ||
| name: Sync static-site docs | ||
|
|
||
| on: | ||
| schedule: | ||
| - cron: '0 9 * * 3' # Weekly on Wednesday | ||
| workflow_dispatch: | ||
|
|
||
| jobs: | ||
| sync: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Create GitHub App Token | ||
| uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1 | ||
| id: app-token | ||
| with: | ||
| client-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_CLIENT_ID }} | ||
| private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }} | ||
|
|
||
| # certified-assets is not a submodule: the build resolves no file from it. | ||
| # A blobless clone is only needed to reason about refs (is the latest | ||
| # release already contained in the pin, did docs/ change), which the | ||
| # contents API cannot answer. | ||
| - name: Clone certified-assets | ||
| run: git clone --filter=blob:none --no-checkout https://github.com/dfinity/certified-assets.git /tmp/certified-assets | ||
|
|
||
| - name: Resolve the ref to sync | ||
| id: check | ||
| env: | ||
| GH_TOKEN: ${{ steps.app-token.outputs.token }} | ||
| run: | | ||
| PIN=$(node -p "require('./.sources/upstream.json').synced.find(e => e.repo === 'dfinity/certified-assets').pinned") | ||
| echo "pin=$PIN" >> $GITHUB_OUTPUT | ||
|
|
||
| # Stable releases only, the same pattern the upstream.json watcher uses. | ||
| # `^v[0-9]` would accept v0.4.0-rc.1 and publish docs for a prerelease. | ||
| TAG=$(git -C /tmp/certified-assets tag --sort=-version:refname \ | ||
| | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1) | ||
| echo "Pinned: $PIN. Latest release: $TAG." | ||
| echo "tag=$TAG" >> $GITHUB_OUTPUT | ||
|
|
||
| # The pin is allowed to sit ahead of the latest release while a docs | ||
| # fix has shipped but a release has not (the state this sync started | ||
| # in). Syncing the tag then would publish older prose. | ||
| if git -C /tmp/certified-assets merge-base --is-ancestor "$TAG" "$PIN"; then | ||
| echo "Pin already contains $TAG. Nothing to sync." | ||
| echo "needed=false" >> $GITHUB_OUTPUT | ||
| exit 0 | ||
| fi | ||
|
|
||
| # Skip only when a PR is actually open. A branch on its own proves | ||
| # nothing: if a previous run pushed and then failed at `gh pr create`, | ||
| # treating the branch as a PR would strand that release forever, with | ||
| # nothing to review and no further attempts. | ||
| BRANCH="infra/sync-static-site-${TAG}" | ||
| echo "branch=$BRANCH" >> $GITHUB_OUTPUT | ||
| if [ -n "$(gh pr list --head "$BRANCH" --state open --json number --jq '.[].number')" ]; then | ||
| echo "A PR for $BRANCH is already open. Skipping." | ||
| echo "needed=false" >> $GITHUB_OUTPUT | ||
| exit 0 | ||
| fi | ||
| if git ls-remote --exit-code origin "refs/heads/${BRANCH}" > /dev/null 2>&1; then | ||
| echo "Branch $BRANCH exists with no open PR (an earlier run stopped" | ||
| echo "between push and PR creation). Deleting it so this run can retry." | ||
| git push origin --delete "$BRANCH" | ||
| fi | ||
|
|
||
| # A release that ships canister changes without touching docs/ leaves | ||
| # the synced pages byte-identical, so there is no content to review. | ||
| # The pin still has to move: it is allowed to sit on a commit only | ||
| # while no release carries the pages, and skipping here would strand | ||
| # it on that commit for good. So the PR is opened either way, and the | ||
| # body says which of the two it is. | ||
| CHANGED=$(git -C /tmp/certified-assets diff --name-only "${PIN}..${TAG}" -- docs/) | ||
| echo "needed=true" >> $GITHUB_OUTPUT | ||
| if [ -z "$CHANGED" ]; then | ||
| echo "No docs/ changes between $PIN and $TAG: advancing the pin only." | ||
| echo "pin_only=true" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "Changed upstream pages:" | ||
| echo "$CHANGED" | ||
| echo "pin_only=false" >> $GITHUB_OUTPUT | ||
| echo "changed_files<<EOF" >> $GITHUB_OUTPUT | ||
| echo "$CHANGED" >> $GITHUB_OUTPUT | ||
| echo "EOF" >> $GITHUB_OUTPUT | ||
| fi | ||
|
|
||
| - name: Move the pin to the release tag | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: | | ||
| node -e ' | ||
| const fs = require("fs"); | ||
| const file = ".sources/upstream.json"; | ||
| const config = JSON.parse(fs.readFileSync(file, "utf8")); | ||
| const entry = config.synced.find((e) => e.repo === "dfinity/certified-assets"); | ||
| entry.pinned = process.argv[1]; | ||
| fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n"); | ||
| ' "$TAG" | ||
| env: | ||
| TAG: ${{ steps.check.outputs.tag }} | ||
|
|
||
| - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 | ||
| if: steps.check.outputs.needed == 'true' | ||
| with: | ||
| node-version: 22 | ||
| cache: npm | ||
|
|
||
| - name: Install dependencies | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: npm ci | ||
|
|
||
| - name: Run static-site docs sync | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: npm run sync:static-site | ||
| env: | ||
| GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} | ||
|
|
||
| # The synced tree is deliberately not in the validator's SYNCED allowlist: | ||
| # the sync normalizes and rewrites so that the pages pass the same checks | ||
| # as a hand-written page, and an exemption would hide the day they stop. | ||
| - name: Validate | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: npm run validate | ||
|
|
||
| # Same set and the same URL rewrite as build.yml. `.gitmodules` uses SSH | ||
| # URLs, which a runner cannot fetch, and `.sources/motoko` is required | ||
| # because pages under docs/languages/motoko/ pull code through | ||
| # `file=<motokoExamples>/...` includes: without it they render empty | ||
| # without failing the build, so this step would have reported a passing | ||
| # build for a site with empty Motoko pages. | ||
| - name: Initialize submodules (required for build) | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: | | ||
| git config --global url."https://github.com/".insteadOf "git@github.com:" | ||
| git submodule update --init --depth 1 .sources/examples .sources/motoko | ||
|
|
||
| - name: Build check | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: npm run build | ||
|
|
||
| - name: Create PR | ||
| if: steps.check.outputs.needed == 'true' | ||
| run: | | ||
| git config user.name "pr-automation-bot-public[bot]" | ||
| git config user.email "pr-automation-bot-public[bot]@users.noreply.github.com" | ||
|
|
||
| BRANCH="infra/sync-static-site-${TAG}" | ||
| git checkout -b "$BRANCH" | ||
| git add .sources/upstream.json docs/guides/frontends/static-site | ||
| git commit -m "chore: sync static-site docs to dfinity/certified-assets ${TAG}" | ||
| git push -u origin "$BRANCH" | ||
|
|
||
| { | ||
| echo "## Summary" | ||
| echo "" | ||
| echo "Automated sync of the certified-assets user docs." | ||
| echo "" | ||
| echo "**Release:** \`$TAG\` (pinned from \`$PIN\`)" | ||
| echo "" | ||
| if [ "$PIN_ONLY" = "true" ]; then | ||
| echo "No page changed in this range. The pin moves off a commit and onto" | ||
| echo "the release tag, so the only diff is \`source_ref\` on each page." | ||
| else | ||
| echo "**Changed upstream files:**" | ||
| while IFS= read -r f; do | ||
| [ -n "$f" ] && echo "- \`$f\`" | ||
| done <<< "$CHANGED" | ||
| fi | ||
| echo "" | ||
| echo "- Ran \`npm run sync:static-site\`, regenerating \`docs/guides/frontends/static-site/\`" | ||
| echo "- Validator and build passed" | ||
| echo "" | ||
| echo "## Checklist" | ||
| echo "" | ||
| echo "- [ ] Review the page diffs for content changes" | ||
| echo "- [ ] Check whether a behavior change contradicts our own Frontends pages (\`certification.md\`, \`asset-canister.md\`)" | ||
| echo "- [ ] Check whether the recipe version named in \`icp.yaml\` examples needs bumping with it" | ||
| } > /tmp/pr-body.md | ||
|
|
||
| gh pr create \ | ||
| --title "chore: sync static-site docs to dfinity/certified-assets ${TAG}" \ | ||
| --body-file /tmp/pr-body.md | ||
| env: | ||
| GH_TOKEN: ${{ steps.app-token.outputs.token }} | ||
| # Values from the upstream repo reach the shell as data, never as | ||
| # script: a filename containing shell metacharacters would otherwise | ||
| # be interpolated into this step's source. | ||
| TAG: ${{ steps.check.outputs.tag }} | ||
| PIN: ${{ steps.check.outputs.pin }} | ||
| CHANGED: ${{ steps.check.outputs.changed_files }} | ||
| PIN_ONLY: ${{ steps.check.outputs.pin_only }} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.