docs: navigation-node CLAUDE.md hierarchy + public-header doc-comments#109
Merged
Conversation
Add per-module navigation nodes for pj_base, pj_datastore, pj_plugins and the pj_plugins/dialog_protocol subfolder; rewrite the submodule-root CLAUDE.md as a pointer hub. Corrections: the dialog C ABI lives in pj_plugins/dialog_protocol/ (not pj_base); clang-format is pinned to v22.1.0; pj_base has 15 builtin struct headers / 14 codecs. Add file/class doc-comments to public headers across the three libraries, and fix doc-vs-code drift in pj_datastore & pj_plugins ARCHITECTURE.md and toolbox-guide.md. Comment/doc-only; no logic changes. PJ4 build + tests unchanged (112/112). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite Release Versioning as a plugin-impact semver contract: MAJOR = ABI/API break (recompile/source change; abi/baseline.abi changes only here), MINOR = backward-compatible addition (old plugins keep working with no recompile; tail-appended, struct_size-gated; abidiff additions-only), PATCH = compatible fixes (consumer-invisible changes take no bump). Define the plugin Conan range [>=X.Y.Z <(X+1).0.0] and the pre-1.0 rule: no breaks within 0.x; the next ABI/API break ships as 1.0.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The abidiff gate (cmake/PjAbiCheck.cmake) existed but was dormant — PJ_ENABLE_ABI_CHECK defaulted OFF and no workflow enabled it. Install abigail-tools, configure with -DPJ_ENABLE_ABI_CHECK=ON, and run the abi_check target after Build so an ABI-incompatible change vs pj_base/abi/baseline.abi fails CI. Makes the Release Versioning policy's 'non-MAJOR must not break ABI' guarantee mechanical rather than aspirational. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The ABI-gate wiring accidentally dropped the 'ccache stats' step header, merging its if/run into the ABI-gate step (two run: keys — GitHub rejects this even though PyYAML's safe_load silently tolerates duplicate keys). Restore the step boundary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…DebInfo) Temporary: the checked-in baseline.abi was captured from a local debug_asan build while the gate runs in RelWithDebInfo, so inline SDK methods elided by the optimizer read as 739 'removed' functions. This dispatch-only step regenerates a config-consistent baseline and uploads it as an artifact; it is removed in the follow-up commit that lands the baseline. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
libabigail's abidw takes --out-file, not -o; the abi_update_baseline target failed with a usage error the first time it was actually run (the gate had been dormant). Permanent fix. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Replace pj_base/abi/baseline.abi with one generated in the same RelWithDebInfo config the gate runs in (the old baseline was a local debug_asan dump, so Release-inlined SDK methods read as 739 phantom 'removed' functions). Baseline + check are now config-consistent and the gate passes; a real ABI break will fail it. Regenerated via abidw in CI. - Remove the temporary dispatch-only regen/upload steps from linux-ci.yml. - Add the missing trailing newline / trim the extra blank line on three CLAUDE.md nodes (end-of-file-fixer; the submodule's local hooks were not installed when they were authored). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Add per-module navigation nodes for pj_base, pj_datastore, pj_plugins and the pj_plugins/dialog_protocol subfolder; rewrite the submodule-root CLAUDE.md as a pointer hub. Corrections: the dialog C ABI lives in pj_plugins/dialog_protocol/ (not pj_base); clang-format is pinned to v22.1.0; pj_base has 15 builtin struct headers / 14 codecs.
Add file/class doc-comments to public headers across the three libraries, and fix doc-vs-code drift in pj_datastore & pj_plugins ARCHITECTURE.md and toolbox-guide.md.
Comment/doc-only; no logic changes. PJ4 build + tests unchanged (112/112).