docs: document per-session config support across all plugins and the spec - #40
Merged
Merged
Conversation
…spec Make per-session config support explicit and discoverable at three layers: 1. PLUGIN-STANDARD.md (spec) — expand the Per-session config section with the author requirement (re-read ctx.config inside the hook, not a cached snapshot), the two correct patterns (per-event re-parse for plain config; config-signature caching for stateful coordinators), an explicit anti-pattern callout (cache-at-enable breaks overrides, the source of PRs #38/#39), and a documentation requirement for READMEs. 2. Root README — add a 'Per-session config support' matrix table after the plugin catalog so operators can see at a glance which plugins honor per-session overrides (✅/⚠️ /❌) and the caveat for each. 3. Each plugin README — add a '### Per-session config' subsection under Compatibility with the support tier (full / caveat / not supported), the fields that may be overridden, and any workaround (e.g. one instance per session for multi-backend isolation or single-sink designs). gsheets-logger's existing note is aligned to the same heading format.
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.
Summary
Make per-session config support explicit and discoverable at three layers. Until now, whether a plugin honors per-session config overrides (different settings for different WhatsApp sessions under one plugin instance) was implicit — readable only from code. This surfaced concretely as the bug class fixed in PRs #38 and #39 (cache-at-enable ignoring overrides).
Problem
OpenWA's
sessionScopedplugins (the default) may carry per-session config overrides set via the dashboard. But a plugin only honors them if it re-readsctx.configinside its hook (not a cached snapshot fromonEnable). This requirement was undocumented in the spec, so:Changes
1.
PLUGIN-STANDARD.md(spec) — the requirementExpanded the existing Per-session config (v0.7) section with:
ctx.configinside the hook; do NOT cache atonEnable.### Per-session config.### Per-session configsubsection under Compatibility.2. Root
README.md— operator-facing matrixAdded a Per-session config support table after the plugin catalog with a ✅/⚠️ /❌ indicator and a one-line note per plugin, linking to each plugin's README for details. This lets an operator see support status at a glance.
3. Each plugin
README.md— per-plugin detailAdded a
### Per-session configsubsection under each plugin's Compatibility section, listing the overridable fields, when an override takes effect, and any caveat/workaround.gsheets-logger's existing note (from #39) is aligned to the same heading format.Verification
npm run catalog:check— up to date (no generated blocks touched).### Per-session configheading.