docs: add a stability policy and record the internal/git structure decision - #417
Merged
Conversation
grut is at v0.8.0 with real usage and no written statement of what is stable, so every config key, JSON field and exit code is currently a contract by accident. docs/stability.md names the surface deliberately: command and flag names, --json output shapes, --check exit codes, config keys, the extension manifest and host functions, and default keybindings. It also names what stays free to change, notably everything under internal/ (which Go already prevents outside code from importing) and TUI rendering. The more useful half is the list of what has to happen before 1.0 is worth tagging. Only two of the ten commands that emit --json have their shape documented, the --check exit codes are undocumented, and the extension manifest has no schema version. Freezing a surface nobody has written down does not achieve much. Also updates the pinned-install examples in README and CONTRIBUTING, which still used v0.1.0 and implied the project was seven minor versions younger than it is. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 98ae0c9c-bdbe-418e-8488-15082edca7dc
doc.go carried a TODO(arch) saying internal/git should be split into sub-packages per issue #167. Acting on it is not possible as written, and the TODO invited someone to try. Every domain file holds methods on *Client, and Go does not allow declaring methods on a type owned by another package. A split would mean fragmenting Client into per-domain clients, which destroys the single GitClient interface the AI middleware implements and every panel consumes, or demoting the methods to free functions, which rewrites every call site while the sub-packages still import git for the Client type. The shared state also argues against it. One OpQueue and one Cache serialise and cache across domains, because a branch operation and a stash operation must not race. Per-domain packages would each need that shared state back, so the coupling relocates rather than dissolves. And the cost is not being felt: roughly 4,000 lines over 30 files, under 140 lines each, already separated and named by domain. The file layout is the split the review asked for. Replaces the TODO with that reasoning plus the signal actually worth watching, which is per-file size rather than file count. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 98ae0c9c-bdbe-418e-8488-15082edca7dc
Task 20 reads as panel wiring, but AnalyzeBranches is not reachable from any panel. Point at #418 so the next person does not rediscover that from scratch. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 98ae0c9c-bdbe-418e-8488-15082edca7dc
Contributor
Benchmarks:
|
Contributor
Benchmarks:
|
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.
Two commits, both writing down decisions that were previously implicit.
1. Stability policy (
docs/stability.md)grut is at v0.8.0 with real usage (v0.7.1 pulled ~1,800 downloads) and no written statement of what is stable. That means every config key, JSON field, and exit code is a contract by accident.
The doc names the surface deliberately:
--jsonoutput shapes (ten commands, fourteen flags counting subcommands)--checkexit codes onclean,doctor,statusAnd what stays free to change: everything under
internal/(Go already prevents outside code from importing it, so it was never an API), TUI rendering, and log formats.The more useful half is the pre-1.0 checklist. Freezing a surface nobody has written down does not achieve much, and right now:
--jsoncommands have their shape documented--checkexit codes are undocumentedAlso refreshes the pinned-install examples in README and CONTRIBUTING, which still used
v0.1.0.2. Why
internal/gitis not split (internal/git/doc.go)doc.gocarried aTODO(arch)saying the package should be split into sub-packages per #167. I looked at doing it and concluded it should not be done, so the TODO is replaced with the reasoning rather than left inviting someone to try.It is not possible as written. Every domain file holds methods on
*Client, and Go does not allow declaring methods on a type owned by another package. A split means either fragmentingClientinto per-domain clients, which destroys the singleGitClientinterface that the AI middleware implements and every panel consumes, or demoting the methods to free functions, which rewrites every call site while the sub-packages still importgitfor theClienttype.The shared state is load-bearing. One
OpQueueand oneCacheserialise and cache across domains, because a branch operation and a stash operation must not race. Per-domain packages each need that state back, so the coupling relocates rather than dissolves.The cost is not being felt. Roughly 4,000 lines over 30 files, averaging under 140 lines each, already separated and named by domain. The largest is
undo.goat 452 lines, within the repo's own 500-line guidance. The file layout is the split the review asked for.#167 was an automated review that counted files and domains. That heuristic is a reasonable smell test, but here it fires on a package whose cohesion is deliberate. The doc now records the signal actually worth watching: per-file size, not file count.
Verification
go build ./...,go vet ./...,gofmt -lclean,go test ./...green. All doc links resolve.