docs(addon-development): Summary sections and verified corrections (6.1) - #1000
Draft
eduralph wants to merge 1 commit into
Draft
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
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.
The
maintenance/gramps61counterpart of #999 — same regenerated content, so the two copies ofdocs/addon-development/stay identical.The exported tree is byte-identical to the one in #999; see that PR for the full rationale. In brief:
Summaryinstead of a one-line stub.03-addon-kinds: 14 → 16 registration kinds (REPORT(0)…CITE(15);QUICKREPORTis a deprecated alias ofQUICKVIEW).16-guidelines: addon-root__init__.pydrops MUST NOT → SHOULD NOT with a MAY carve-out — seven addons ship one and work, and the old Mantis 12691 citation describes a trap__init__.pyneither causes nor cures.04-fundamentals/16-guidelines:get_addon_translatormust be guarded against theValueErrorit raises when no compiled catalog exists and no configured language starts withen/C.09-troubleshoot: new entry forCustomFiltersbeingNoneunder test.12-packaging:LANGUAGE='en_US.UTF-8'dropped from themake.pyrecipe;as-neededandmanifest-checkdocumented.07-testing: thetests/package asymmetry re-argued on grounds that hold.README.mdand_media/are unchanged; the diff is exactly the 17 pages.Draft until reviewed. Merge after #999 so the two branches don't diverge.