docs(how-to): add backend authoring guide#155
Merged
Conversation
Add comprehensive Backend Authoring Guide covering the EncryptionBackend protocol contract, backend ID assignment, AesGcmBackend walkthrough, starter template, registration, testing checklist, common pitfalls, and security notes. Fix __all__ sort order in root __init__.py and add parametrized test enforcing alphabetical sort across all __init__.py files.
Code review found the starter template's sync_decrypt used except Exception which caught the NotImplementedError placeholder, and ConfigurationError was referenced in comments but not imported. Also improved test checklist specificity and corrected cross-cutting task bookkeeping.
There was a problem hiding this comment.
Pull request overview
Adds a new “Backend Authoring” how-to guide to help contributors implement custom EncryptionBackend implementations without reading library internals, and tightens public API hygiene with a new __all__ ordering test.
Changes:
- Added
docs/how-to/backend-authoring.mdwith protocol contract, backend ID guidance, registration steps, testing checklist, pitfalls, and security notes. - Updated
mkdocs.ymlto include “Backend Authoring” under How-To Guides. - Added a unit test to enforce alphabetical
__all__ordering across package__init__.pymodules and fixed root__all__ordering.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_public_api.py | Adds a parametrized test enforcing sorted __all__ in key package modules. |
| src/adk_secure_sessions/init.py | Reorders __all__ entries to satisfy alphabetical ordering. |
| mkdocs.yml | Adds the new Backend Authoring page to the docs navigation. |
| docs/how-to/backend-authoring.md | New backend authoring guide covering implementation, registration, and testing guidance. |
| _bmad-output/test-artifacts/test-review.md | Updates the generated test review artifact metadata/content for a newer review run. |
| _bmad-output/implementation-artifacts/sprint-status.yaml | Marks stories 4.4 and 4.5 as done. |
| _bmad-output/implementation-artifacts/4-5-backend-authoring-documentation.md | Adds story artifact write-up, but contains scope statements that contradict this PR’s actual changes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Cross-cutting task added __init__.py sort fix and test_public_api.py test, but Dev Notes still said "no src/ changes". Added cross-cutting acknowledgment and removed __init__.py from the "no changes" list.
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.
Backend authors (Epic 5 dev agents and community contributors) had no
documentation for implementing custom encryption backends. They had to
read library source code to understand the EncryptionBackend protocol,
registration, and testing patterns.
docs/how-to/backend-authoring.mdwith 10 sections: protocolcontract, backend ID assignment, AesGcmBackend walkthrough, starter
template, registration instructions, testing checklist, common
pitfalls, security notes, and related links
Backend Authoringnav entry under How-To Guides in mkdocs.ymlTestAllAlphabeticallySortedparametrized test covering all 3__init__.pyfiles (cross-cutting); fix root__all__sort ordersync_decrypterror-wrapping anti-pattern andmissing
ConfigurationErrorimport (code review)Test:
pre-commit run --all-files && uv run mkdocs build --strictPR Review
Checklist
uv run pytest)uv run ruff check .)!in title andBREAKING CHANGE:in bodyReview Focus
Related