|
bashdeps
Exact dependency materialization and manifest maintenance tools
|
Accepted
This Architecture Decision Record extends the existing Doxygen publication workflow with a generated ADR landing page while keeping mechanically generated navigation out of maintained source control.
The repository SHALL maintain the stable prose that frames the ADR corpus, SHALL use adrctl generate toc for mechanical ADR title/link enumeration, and SHALL compose those inputs into an ephemeral doc/adr/README.md during documentation generation. Doxygen SHALL use that generated Markdown file as the main page of the published reference site.
The generated landing page is a build input and publication artifact, not a maintained repository document. The authoritative sources remain the individual ADRs, maintained framing fragments, and doc/decisions.md.
This decision does not add an ADR relationship graph. The linked textual table of contents is the normal navigation surface.
ADR-016 established make docs as the canonical local and CI path for Doxygen reference generation and established doc/reference/ as ignored generated output. ADR-017 later moved the Doxygen filter into manifest-managed dependency state while retaining the repository's bootstrap and dependency trust boundaries.
The resulting GitHub Pages site is useful as source reference documentation, but its index currently lacks a repository-level body of documentation. A reader who arrives at the site does not receive the ADR-oriented context and navigation that now works well in bashlog.
The ADR corpus already contains the information needed to construct a linked index. Maintaining a second hand-written title list would duplicate filenames and titles and would predictably drift. adrctl already owns ADR discovery and TOC serialization, so bashdeps should consume that report rather than implement a second ADR parser.
An earlier implementation draft considered committing the generated doc/adr/README.md. That approach makes the file useful when browsing the ADR directory directly on GitHub, but it also creates a synchronization obligation: every ADR change that affects the index must carry an otherwise derivative file change, and CI must distinguish a current generated file from a stale one. The primary requirement here is the published documentation site, not GitHub's directory README behavior.
The project already treats generated Doxygen HTML as reproducible derivative output. Treating the generated Markdown landing page as another ephemeral stage of the same documentation pipeline gives the project a clearer boundary: maintained prose and ADRs are source; generated navigation and HTML are products of the documentation build.
adrctl rather than creating another ADR discovery implementation.make docs as the canonical documentation-generation entry point.The repository SHALL maintain:
These files own stable repository-specific prose around the mechanically generated ADR list.
Documentation generation SHALL compose those maintained files with adrctl generate toc output into:
The generated README.md SHALL be ignored by Git and SHALL NOT be committed as ordinary repository state.
The responsibility split is:
The repository SHALL add a released adrctl.bash artifact to dependencies.txt at:
The initial pin SHALL use adrctl v0.0.13 and its release-published SHA-256 digest.
adrctl is development/documentation tooling only. It SHALL NOT be concatenated, embedded, sourced, or otherwise incorporated into bashdeps.bash or manifest-manager.bash release artifacts.
The existing Make-owned vendor/bashdeps.bash bootstrap remains outside the manifest because the dependency manager cannot use its own manifest to obtain its first executable copy.
The Makefile SHALL expose:
The target SHALL consume already-prepared vendor/adrctl.bash state. It SHALL NOT invoke dependency synchronization itself.
adr-index SHALL:
generate toc with the maintained intro and outro fragments;doc/adr/README.md only after successful generation.Generation therefore remains safe against an ordinary failed report leaving a partially written landing page at the selected destination.
The Makefile MAY expose conventional variables for the ADR directory, generated index, framing files, and adrctl path so the implementation is inspectable and adaptable without teaching adrctl repository-specific layout policy.
make docs SHALL ensure dependency state is prepared according to the existing ADR-017 behavior and SHALL invoke adr-index before Doxygen.
The sequencing SHALL be explicit. The implementation SHALL NOT rely on parallel Make prerequisite ordering to ensure that adrctl exists before ADR index generation begins.
docs-clean SHALL continue to remove Doxygen output under doc/reference/ and SHALL NOT be a prerequisite that races with ADR index generation. The generated ADR index may remain in the working tree as ignored derivative state after make docs completes.
A complete generated-state cleanup path MAY remove the ephemeral ADR index along with other generated state.
Doxygen SHALL consume maintained Markdown documentation and the generated doc/adr/README.md in addition to maintained source documentation.
The Doxyfile SHALL use:
The generated HTML under doc/reference/ remains ignored and ephemeral. Making the generated ADR index the Doxygen main page does not make either generated surface authoritative documentation source.
Normal documentation generation SHALL NOT invoke adrctl generate graph, embed Mermaid source, render DOT/Graphviz relationship diagrams, or add graph-specific link configuration merely as part of ADR navigation.
This does not remove or deprecate graph capabilities from adrctl and does not prohibit unrelated diagrams governed by other project decisions. It establishes only that the ordinary project landing page uses the linked textual ADR index.
README.intro.md and README.outro.md.doc/adr/README.md is generated during documentation work and is not committed.make docs remains the canonical documentation entry point.doc/adr/ directly on GitHub is not promised to show the generated table of contents as a directory README.doc/decisions.md or summarize decision rationale.bashdeps.bash or manifest-manager.bash public behavior.The pinned adrctl artifact executes with the authority of the documentation build and therefore becomes part of the documentation trusted computing base. Its committed SHA-256 digest authorizes exact expected bytes but does not prove those bytes are behaviorally safe. Dependency review remains required.
A failed report generator could otherwise leave truncated or partial Markdown. Same-directory temporary generation followed by replacement only on success bounds that ordinary failure mode.
A compromised or defective generator could produce incorrect links or prose. The maintained ADRs and framing remain reviewable source, while publication and CI provide observable generated output. The generated page is deliberately not promoted into authoritative source merely because Doxygen publishes it.
The implementation MUST preserve the product source closures. Documentation-only adrctl bytes must not become part of either released executable.
The implementation also avoids executing ADR Markdown or framing files as shell code. They are data consumed by adrctl and ordinary file composition.
vendor/adrctl.bash MUST be declared in dependencies.txt with an immutable release URL and approved SHA-256 digest.make adr-index MUST consume prepared dependency state and MUST NOT synchronize dependencies.make docs MUST sequence dependency preparation before ADR index generation.doc/adr/README.intro.md and doc/adr/README.outro.md MUST remain maintained source.doc/adr/README.md MUST be generated atomically and MUST be ignored by Git.doc/reference/ output MUST remain ignored and ephemeral.adrctl generate graph or add a relationship-graph section.This would make the generated index visible automatically when browsing the ADR directory on GitHub. It was rejected because the primary consumer is the published Doxygen site and committing the derivative page creates an avoidable synchronization and CI-drift obligation.
This avoids another documentation dependency, but duplicates ADR filenames and titles in maintained source and creates predictable drift. It was rejected.
The implementation could be short, but it would create another definition of ADR discovery and title extraction. adrctl already owns those semantics and is the appropriate focused producer.
The decision map is useful maintained prose, but its purpose is concise decision summary rather than mechanically complete ADR navigation. Keeping those roles separate makes both documents clearer.
This would satisfy hosted publication but would make local make docs differ from the Pages build. The canonical Make target should produce the same documentation shape locally and in CI.
This would be convenient from a pristine checkout but would blur the repository's existing dependency boundaries. The focused generation target consumes prepared state; the higher-level documentation target performs whatever preparation its existing governance allows.
The graph adds renderer and presentation complexity while providing less practical navigation value than the linked textual index. The routine documentation path therefore remains text-only.
The GitHub Pages site gains a useful project-level entry page without adding a committed derivative Markdown file.
The repository gains two small maintained framing documents and one pinned executable documentation dependency. The documentation trusted computing base therefore expands by the reviewed adrctl artifact.
Local make docs leaves an ignored generated doc/adr/README.md in addition to ignored doc/reference/ output. That makes the intermediate page inspectable without turning it into maintained source.
Doxygen becomes a broader documentation portal by processing selected maintained Markdown as well as source-level Doxygen comments. Runtime behavior, release artifact count, and executable source closures remain unchanged.
1.9.8