Skip to content

docs(addon-development): Summary sections and verified corrections - #999

Draft
eduralph wants to merge 1 commit into
gramps-project:maintenance/gramps60from
eduralph:docs/addon-manual-summary-pass
Draft

docs(addon-development): Summary sections and verified corrections#999
eduralph wants to merge 1 commit into
gramps-project:maintenance/gramps60from
eduralph:docs/addon-manual-summary-pass

Conversation

@eduralph

Copy link
Copy Markdown
Contributor

Follow-up to #994. Regenerated from the docs-as-code source; the vault stays the single source of truth and this tree is deterministic output.

What changed

Every page now opens with a real Summary — what it covers, in what order, and when to come back to it — instead of a one-line stub.

Corrections, each checked against this repository and gramps on maintenance/gramps60:

Page Change Evidence
03-addon-kinds 14 → 16 registration kinds REPORT(0)…CITE(15) in gramps/gen/plug/_pluginreg.py; QUICKREPORT is a deprecated alias of QUICKVIEW, not a separate kind
16-guidelines addon-root __init__.py: MUST NOT → SHOULD NOT, with a MAY carve-out Seven addons here ship one and work — DynamicWeb, ExcludeSubtreeFilter, GrampyScript, PlaceCleanup, PostgreSQLEnhanced, Query, Sqlite (six are empty files)
04-fundamentals, 16-guidelines get_addon_translator must be guarded It raises ValueError when no compiled catalog exists and no configured language starts with en/C
09-troubleshoot new entry: CustomFilters is None under test reload_custom_filters() rebinds the module global, so importing the name first captures None permanently
12-packaging LANGUAGE='en_US.UTF-8' dropped from the make.py recipe make.py on this branch never reads it; adds the as-needed and manifest-check targets
07-testing tests/ package asymmetry re-argued Old rationale didn't hold — see below

On the __init__.py downgrade

The previous rule cited Mantis 12691 in support. That bug is a different trap — from <Addon> import <Addon> binding the submodule instead of the class, caused by the addon dir's parent being on sys.path — which a namespace package hits identically. __init__.py neither causes nor cures it, so the citation is withdrawn.

What the file actually costs is consistency across contexts: run from the repo root, as tests are, the same module is also reachable as <Addon>.<module>, giving two module objects and two copies of every module-level global. PluginManager.import_plugin inserts the addon's own directory at sys.path[0] and does a top-level __import__, so the root __init__.py never runs on the load path at all.

A rule that seven shipping addons violate without producing a defect doesn't meet this page's own bar for MUST. 17-roadmap records the open question of whether CI should flag it — advisory at most, since a gate would start red.

Notes

  • README.md and _media/ are unchanged; the diff is exactly the 17 pages.
  • The export is deterministic — re-running it against this branch leaves an empty git diff.
  • A matching PR targets maintenance/gramps61.
  • Draft until reviewed.

Regenerated from the docs-as-code source. Every page now opens with a
"Summary" section that says what it covers, in what order, and when to come
back to it, instead of a one-line stub.

Corrections carried in the same pass, each checked against this repository
and gramps on maintenance/gramps60:

- 03-addon-kinds: 14 -> 16 registration kinds. REPORT(0)..CITE(15) in
  gramps/gen/plug/_pluginreg.py; QUICKREPORT is a deprecated alias of
  QUICKVIEW, not a separate kind.
- 16-guidelines: addon-root __init__.py drops from MUST NOT to SHOULD NOT,
  with a MAY carve-out for addons that genuinely expose a package API.
  Seven addons here ship one today (DynamicWeb, ExcludeSubtreeFilter,
  GrampyScript, PlaceCleanup, PostgreSQLEnhanced, Query, Sqlite) and work.
  The previous rationale cited Mantis 12691, which is a different trap that
  __init__.py neither causes nor cures; the real cost is that the same
  module becomes reachable under two names between the runtime and test
  views. PluginManager.import_plugin does a top-level __import__, so the
  file never runs on the load path.
- 04-fundamentals, 16-guidelines: get_addon_translator must be guarded —
  it raises ValueError when no compiled catalog exists and no configured
  language starts with en/C, so the unguarded form passes on an
  English-locale machine and crashes at import for the first user running
  a non-English UI. Adds the help_url rule (Addon:PageName, not a GitHub
  URL).
- 09-troubleshoot: new entry for CustomFilters being None under test —
  reload_custom_filters() rebinds the module global, so importing the name
  first captures None permanently.
- 12-packaging: LANGUAGE='en_US.UTF-8' removed from the make.py recipe
  (make.py on this branch never reads it); as-needed and manifest-check
  targets documented.
- 07-testing: the tests/ package asymmetry re-argued on the grounds that
  actually hold.
- 17-roadmap: opens the question of whether CI should flag an addon-root
  __init__.py — advisory at most, since a gate would start red on the
  seven addons that ship one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant