docs: add interface-first plugin authoring guide#3132
Draft
sfc-gh-olorek wants to merge 1 commit into
Draft
Conversation
Add docs/contributing/writing-a-plugin.md describing the interface-first plugin pattern: the two-phase contribution workflow, defining the command surface in interface.py, implementing handler.py, testing the spec/handler contract, and wiring it together with build_command_spec. Link it from the CONTRIBUTING.md "Detailed guides" index and cross-link it from adding-commands.md as an alternative to the classic command layout.
9 tasks
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.
Pre-review checklist
RELEASE-NOTES.md(see when and how).Documentation-only PR: no user-facing interface, no code/tests, no platform-specific behavior — those items are N/A.
skip-release-notesapplied.Changes description
Split out from #2862 (the original PR is now the cookiecutter template only).
Adds
docs/contributing/writing-a-plugin.md, a contributor guide for theinterface-first plugin pattern:
interface.py(spec dataclasses + handler ABC).handler.pyand wiring it withbuild_command_spec.snowflake.cli.api.plugins.command.testinghelpers.Linked from the
CONTRIBUTING.mdDetailed guides index and cross-linked fromadding-commands.mdas an alternative to the classic command layout (consistentwith how the lean
CONTRIBUTING.mddelegates detail todocs/contributing/*).All API references were checked against current
main:build_command_specisimported from
...command.bridge, theParamDef/spec examples match the currentdataclasses, and the Phase 2 example follows
conventions.mdSQL-safety rules(
to_string_literal, no raw interpolation).Pairs with #2862 (the cookiecutter template). Merge #2862 first so the
plugin-template/references in this guide resolve onmain.