docs(build): pin the deploy tooling, correct the hook macro-scope note #18

2026-10-15T18:28:55Z

hermes commented

2026-10-15 18:28:55 +00:00

What

Addresses the two remaining findings from the review of #16 (both already merged to main).

1. Pinned deploy tooling (`.gitea/workflows/publish.yml`)

The publish workflow installed everything unpinned, so a breaking or compromised upstream release would ship straight to the live site on the next merge to main. Now pinned to the versions the site builds with today:

cloudron-surfer@6.4.1
mkdocs==1.6.1, mkdocs-material==9.7.7, fontawesome_markdown==0.2.6, mkdocs-redirects==1.2.3
@marp-team/marp-cli@4.5.1

Plus a committed .npmrc with ignore-scripts=true and save-exact=true, so package install scripts cannot run during the deploy. Neither npm package ships an install, preinstall or postinstall hook (checked against the published package metadata), so nothing is skipped.

2. The LIBREF/DS macro-scope note (`two-rule-sets-one-table.md`)

The section claimed a %let "creates a new variable in the hook's own scope and is silently discarded" while call symputx updates the existing one. That is not how SAS resolves it. LIBREF and DS are created with %let inside mpe_loader and so already exist in an enclosing symbol table; a macro only gets a new local when the name is absent from every enclosing table (or is explicitly declared %local), so both forms assign to the same variable. Reworded to state that, keeping the practical advice that call symputx is explicit and does not depend on the enclosing scope still holding the name.

Verification

mkdocs build --clean succeeds with the exact pinned versions installed together; the built two-rule-sets-one-table page carries the new wording and no longer contains the old claim.
The workflow YAML parses.

Not in this PR

The other two review items from #16 were the .pre-commit-config.yaml hook (added in #17) and the pre-edit hook page corrections (also #17).

## What Addresses the two remaining findings from the review of #16 (both already merged to `main`). ### 1. Pinned deploy tooling (`.gitea/workflows/publish.yml`) The publish workflow installed everything unpinned, so a breaking or compromised upstream release would ship straight to the live site on the next merge to `main`. Now pinned to the versions the site builds with today: - `cloudron-surfer@6.4.1` - `mkdocs==1.6.1`, `mkdocs-material==9.7.7`, `fontawesome_markdown==0.2.6`, `mkdocs-redirects==1.2.3` - `@marp-team/marp-cli@4.5.1` Plus a committed `.npmrc` with `ignore-scripts=true` and `save-exact=true`, so package install scripts cannot run during the deploy. Neither npm package ships an `install`, `preinstall` or `postinstall` hook (checked against the published package metadata), so nothing is skipped. ### 2. The LIBREF/DS macro-scope note (`two-rule-sets-one-table.md`) The section claimed a `%let` "creates a new variable in the hook's own scope and is silently discarded" while `call symputx` updates the existing one. That is not how SAS resolves it. `LIBREF` and `DS` are created with `%let` inside `mpe_loader` and so already exist in an enclosing symbol table; a macro only gets a new local when the name is absent from every enclosing table (or is explicitly declared `%local`), so both forms assign to the same variable. Reworded to state that, keeping the practical advice that `call symputx` is explicit and does not depend on the enclosing scope still holding the name. ## Verification - `mkdocs build --clean` succeeds with the exact pinned versions installed together; the built `two-rule-sets-one-table` page carries the new wording and no longer contains the old claim. - The workflow YAML parses. ## Not in this PR The other two review items from #16 were the `.pre-commit-config.yaml` hook (added in #17) and the pre-edit hook page corrections (also #17).

hermes added 2 commits 2026-10-15 18:28:56 +00:00

docs(build): pin the deploy tooling versions and disable install scripts 8ed0f16004

The publish workflow installed cloudron-surfer, the mkdocs pip set and
@marp-team/marp-cli with no version pins, so a breaking or compromised upstream
release would ship straight to the live site on the next merge to main.

- pin cloudron-surfer@6.4.1, mkdocs==1.6.1, mkdocs-material==9.7.7,
  fontawesome_markdown==0.2.6, mkdocs-redirects==1.2.3 and
  @marp-team/marp-cli@4.5.1 (the versions the site builds with today)
- add .npmrc with ignore-scripts=true and save-exact=true; neither npm package
  ships an install/preinstall/postinstall hook, so nothing is skipped

docs(developer-guide): correct the LIBREF/DS macro-scope note 8a22e28a46

The post-edit hook section claimed a `%let` "creates a new variable in the
hook's own scope and is silently discarded" while `call symputx` updates the
existing one. That is not how SAS resolves it: LIBREF and DS already exist in
an enclosing symbol table (mpe_loader's local table), and a macro only gets a
new local when the name is absent from every enclosing table, so both forms
assign to the same variable. Reworded to state that, and to keep the practical
advice (call symputx is explicit and does not depend on the enclosing scope
still holding the name).

Raised in review of #16.

allan merged commit 127f10fba9 into main

2026-10-15 18:56:57 +00:00

allan deleted branch docs/pin-deploy-and-hook-scope

2026-10-15 18:56:57 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dc/docs.datacontroller.io#18