docs(addon-development): Summary sections and verified corrections - #999
Draft
eduralph wants to merge 1 commit into
Draft
docs(addon-development): Summary sections and verified corrections#999eduralph wants to merge 1 commit into
eduralph wants to merge 1 commit into
Conversation
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.
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
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.
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:03-addon-kindsREPORT(0)…CITE(15) ingramps/gen/plug/_pluginreg.py;QUICKREPORTis a deprecated alias ofQUICKVIEW, not a separate kind16-guidelines__init__.py: MUST NOT → SHOULD NOT, with a MAY carve-outDynamicWeb,ExcludeSubtreeFilter,GrampyScript,PlaceCleanup,PostgreSQLEnhanced,Query,Sqlite(six are empty files)04-fundamentals,16-guidelinesget_addon_translatormust be guardedValueErrorwhen no compiled catalog exists and no configured language starts withen/C09-troubleshootCustomFiltersisNoneunder testreload_custom_filters()rebinds the module global, so importing the name first capturesNonepermanently12-packagingLANGUAGE='en_US.UTF-8'dropped from themake.pyrecipemake.pyon this branch never reads it; adds theas-neededandmanifest-checktargets07-testingtests/package asymmetry re-arguedOn the
__init__.pydowngradeThe 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 onsys.path— which a namespace package hits identically.__init__.pyneither 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_plugininserts the addon's own directory atsys.path[0]and does a top-level__import__, so the root__init__.pynever 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-roadmaprecords the open question of whether CI should flag it — advisory at most, since a gate would start red.Notes
README.mdand_media/are unchanged; the diff is exactly the 17 pages.git diff.maintenance/gramps61.