docs: add plans/ directory for design and implementation plans#3317
Open
martin-belanger wants to merge 1 commit intolinux-nvme:masterfrom
Open
docs: add plans/ directory for design and implementation plans#3317martin-belanger wants to merge 1 commit intolinux-nvme:masterfrom
martin-belanger wants to merge 1 commit intolinux-nvme:masterfrom
Conversation
martin-belanger
force-pushed
the
add-plans
branch
from
43317e4 to
aaa2232
Compare
Introduce a new top-level `plans/` directory to host design and implementation plans for larger refactoring efforts. These documents capture the rationale, architecture, and step-by-step implementation strategy for non-trivial changes before code is written. Many of these plans are developed with the assistance of AI tools (e.g. ChatGPT for prompt refinement/review and Claude for code analysis and plan drafting), and then reviewed/edited by maintainers. The goal is to: - make design intent explicit and reviewable - reduce iteration during implementation - provide a reference for future contributors - allow the flexibility of having one person draft a plan and pass it on to another to execute it. No functional changes. Signed-off-by: Martin Belanger <[email protected]>
martin-belanger
force-pushed
the
add-plans
branch
from
aaa2232 to
a992ae8
Compare
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.
Add initial design plan (v10) under
plans/This adds the current design/implementation plan for the Python bindings + accessor refactor under
plans/.@dwsuse - You previously reviewed an earlier version (v6). This update reflects a few targeted refinements rather than a redesign:
Key changes from v6 → v10
1) SWIG Access model (main change)
generated→ direct struct access (p->member)custom→ accessor functionnone→ no accessRationale: generated accessors are trivial; custom accessors handle the real logic.
2) Removed
!access:nested&fctx->cfg)3) Generated setter semantics (updated)
write=generatedis allowed for all supported typeschar *→free + strdupRationale: allows safe generation while keeping special cases in
customwhen needed.4) Lifecycle annotation (new)
Added struct-level lifecycle control:
!generate-lifecycle=generated!generate-lifecycle=customGenerated lifecycle:
char *) + structRationale: makes ownership and allocation explicit and generator-driven.
5) Generator + typemap alignment
generatedcustom%immutableforwrite=none6) Invariants clarified
A field is exposable if it has a usable access path:
read != noneorwrite != noneEverything else (dict-based API, callbacks, lifetime model, generator structure, etc.) remains unchanged.
The goal of these changes is to simplify the bindings, reduce unnecessary indirection, and make the generator behavior more explicit and predictable.
Happy to adjust anything if you think this is going in the wrong direction.