mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-07 03:15:56 +00:00
kevinveenbirkenbachandClaude Opus 4.7
7d7301614d
Add cli/contributing/changelog/archive: a CLI that trims CHANGELOG.md
to the last N entries (default 7) and writes every older release to
its own file under docs/changelog/ named <padded-semver>-<date>.md
(7.0.0 → 007.000.000-2026-05-08.md). The padded form makes a directory
listing already chronological, and the index in CHANGELOG.md is
rebuilt from the archive directory listing on every run, so it never
drifts away from what is on disk. The tool is idempotent and never
overwrites an existing archive file.
Run the migration once to split the 44-entry CHANGELOG.md into 7
inline entries plus 37 archived per-release files, with the index at
the bottom of CHANGELOG.md linking each archive in descending order.
Add docs/contributing/actions/release.md as the contributor-facing
release procedure (versioning, active window vs. archive, cutting a
release end-to-end, CI hand-off on tag push) and add a docs README
under docs/changelog/ that explains the archive directory layout and
filename schema. Cross-link release.md from pipeline.md and add
"releases" to the actions/ scope description.
Documentation cleanup pass on every page touched in the previous
mapping refactor:
- Remove "is the SPOT for X" / "Single Point of Truth" self-labels
across docs/contributing/, docs/agents/, and docs/changelog/. The
rule in documentation.md forbids self-declared SPOT status; status
is conferred by readers cross-linking, not by the page asserting
it. Rephrase to descriptive phrasing ("This page covers X",
"describes X", "lists X") throughout.
- Drop the orphaned docs/contributing/tools/actions.md duplicate
(101 lines paralleling tools/github/actions/workflows.md, with no
inbound links).
- Fix em-dashes used as thought breaks in dockerfile.md, origin.md,
agents/style.css.md, and suppression.md per documentation.md.
- Unwrap soft-wrapped sentences in iam/common.md, iam/ldap.md,
iam/oidc.md, image/origin.md, requirements.md, and dockerfile.md
so each logical line carries one full sentence.
Add a unit test for the archive CLI under
tests/unit/cli/contributing/changelog/archive/test_main.py covering
_pad_version, _split_into_entries, idempotency, dry-run, no-overwrite
of existing archives, and the multi-run index rebuild.
Quote `# noqa:` in CHANGELOG.md prose with backticks so the
noqa-only-ruff-codes lint does not parse "for" as a non-ruff code.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
37 lines
2.9 KiB
Markdown
37 lines
2.9 KiB
Markdown
# javascript.js
|
|
|
|
This page covers automatically generating and updating role-local `javascript.js`, `javascript.js.j2`, and equivalent injected browser entry files.
|
|
Use this page for implementation scope, DOM strategy, and live review.
|
|
For injector wiring, activation, and repository-wide behavior rules, see [Contributing `javascript.js`](../../../contributing/artefact/files/role/javascript.js.md).
|
|
|
|
## Goal
|
|
|
|
- You MUST use role-local JavaScript only for browser-side gaps that cannot be solved cleanly through app configuration, server configuration, or CSS alone.
|
|
- Keep injected scripts small, explicit, and tightly scoped to the role's real integration need.
|
|
- Write the result so it adapts the upstream UI without turning the injected script into a fork of the application's frontend.
|
|
|
|
## Implement
|
|
|
|
- You MUST use `templates/javascript.js.j2` when runtime values from the inventory or role variables must be rendered into the browser code.
|
|
- You MUST use `files/javascript.js` when the script is static and does not depend on templating.
|
|
- You MUST wait for the DOM before touching elements, and guard missing elements so unrelated pages do not break.
|
|
- You MUST keep event handlers, observers, and DOM mutations idempotent because injected scripts may run on dynamic pages or be triggered repeatedly.
|
|
- You MUST prefer stable selectors and narrow hooks over text matching or timing-based hacks.
|
|
|
|
## Avoid
|
|
|
|
- Do NOT reimplement server-side logic, authentication protocols, or business rules in injected JavaScript.
|
|
- Do NOT rewrite large parts of the frontend when a focused event handler, DOM adjustment, or configuration change is enough.
|
|
- Do NOT rely on fragile selectors, broad text matching, or timing hacks when more stable hooks exist.
|
|
- Do NOT introduce noisy debug logging, uncaught errors, duplicate event handlers, or endless observers into injected scripts.
|
|
- Do NOT break native login, logout, navigation, or form flows unless the role explicitly requires that change and the new behavior is verified end to end.
|
|
|
|
## Review
|
|
|
|
- You MUST check the result with live inspection in the running application, not only by reading the JavaScript file.
|
|
- You MUST compare the implemented behavior against the rendered UI so missing hooks, duplicate handlers, broken selectors, and unexpected side effects become visible.
|
|
- You MUST at minimum inspect and compare the start page and the login page because these pages usually expose the most important navigation, authentication, and first-load behavior.
|
|
- You MUST check the browser console for JavaScript errors or repeated side effects after the script is injected.
|
|
- If the change affects user-visible behavior, you MUST add or update the matching end-to-end coverage in [Role `playwright.spec.js`](playwright.spec.js.md).
|
|
- You MUST check that the final JavaScript still feels like a small role-local adaptation of the target application, not a forked frontend implementation.
|