Aman-Mittal opened a new pull request, #65:
URL: https://github.com/apache/fineract-site/pull/65
Automates the steps from #64: building the docs with `./gradlew
asciidoctor`, copying them with `fineract-site docs`, and updating `.htaccess`.
It follows the same pattern as the API spec sync in fineract-backoffice-ui.
## What it does
`.github/workflows/docs-sync.yml` runs every Monday, or by hand with `ref`,
`dry_run` and `force` inputs, and opens a PR against `asf-site`:
| Target | When | Change |
|---|---|---|
| `develop` | `develop` has moved since the commit recorded in the last
`update /docs/*-SNAPSHOT` commit | Refreshes `docs/X.Y.Z-SNAPSHOT/` in place.
If the backend version has rolled after a release, it renames the previous
snapshot folder (as in 3c4e0c1a) and points `/docs/develop` and the commented
`/docs/rc` candidate at the new version. |
| Newest `X.Y.Z` tag | No `docs/X.Y.Z/` yet | Adds it and points
`/docs/stable` (and so `/docs/current`) at it. |
When there's no new release, only the snapshot `index.html` changes: no
rename and no `.htaccess` edit. A rebuild where only the "Built on" or "Last
updated" stamps change opens no PR. Each target uses a fixed branch
(`bot/docs-develop`, `bot/docs-X.Y.Z`), so re-runs update the open PR instead
of adding new ones. Commits are signed by GitHub (`sign-commits`), so
`verify-commits.yml` passes.
## Layout
- `.github/scripts/docs-sync.sh`: `plan` and `build`, which hold all of the
logic. The workflow only calls this script and `docs-sync-pr.sh`, so a run can
be reproduced locally (README, "Automated docs sync").
- `.github/scripts/docs-sync-pr.sh`: turns `DOCS-LOG-MESSAGE` into the
commit message, PR title, branch and body, so no `${{ }}` is interpolated into
shell.
- `.github/docs-sync/package-lock.json`: pins `vega-cli` and `vega-lite`,
which asciidoctor-diagram needs for the Vega-Lite diagrams. Without them the
build still succeeds but leaves the diagrams out, which happened in the
1.16.0-SNAPSHOT build in 61da315.
- `scripts/generate_docs.py`: new `--alias stable|develop` option, which
makes the `.htaccess` and snapshot-rename changes. Manual runs can use it too.
`run_git` now prints git's error message on failure.
- `scripts/test_generate_docs.py`: unit tests for the alias and rename
logic, run by `site-tool test`.
## Security
- `zizmor --persona=pedantic` reports no findings. The one ignore is
`superfluous-actions` on `peter-evans/create-pull-request`, because `gh pr
create` can't make signed commits.
- `actionlint` and `shellcheck` are clean.
- Actions are pinned to commit SHAs, with `persist-credentials: false` and
`permissions: {}` at the top level.
- Only the PR job can write. It has no cache, and its npm install runs with
`--ignore-scripts`.
- It uses `github.token` only. PRs opened with that token don't trigger
other workflows, so the job itself runs the same `site-tool build` and checks
as `site-pr-check.yml`.
## Verified locally
In a standalone clone of this branch:
- `plan`: plans nothing while `develop` is still at the commit the snapshot
docs came from; plans a release build when given `1.16.0`; rejects a malformed
ref.
- `build develop develop` from a simulated pre-roll state (1.16.0-SNAPSHOT):
renamed the folder to `docs/1.17.0-SNAPSHOT` and produced the same `.htaccess`
change as the one made by hand in #64 (identical blob `053bba8`). The site
build, internal link check and Whimsy checks passed.
- Forcing asciidoctor to re-run on the same commit: `changed=false`, so no
PR.
- `docs-sync-pr.sh`: produced the expected commit message, branch and body.
- `site-tool test`: the Ruby suite (23 runs) and the 7 Python tests pass.
## Note
The first run will change the widths of the Vega-Lite diagrams compared with
the hand-built pages. Without the native `canvas` module (skipped by
`--ignore-scripts`), Vega estimates text widths instead of measuring real
fonts. Output is byte-identical from run to run, so this is a one-time diff.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
