mirror of
https://github.com/github/gh-stack.git
synced 2026-09-14 20:26:28 +08:00
Francis Batac
4759126a51
* Add AGENTS.md and copilot-instructions.md for AI agent onboarding Add two complementary instruction files so AI coding agents can work effectively in this repository without re-discovering conventions: - AGENTS.md (7K chars): agent-agnostic open standard with full project structure, build/test commands, coding patterns, testing conventions, error handling, key interfaces, and non-obvious gotchas. - .github/copilot-instructions.md (2K chars): concise Copilot-specific instructions under the 4K code review limit, covering the essentials and referencing AGENTS.md for full details. Closes #132 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: update cmd to generate an executable binary Co-authored-by: Sameen Karim <skarim@github.com> * fix: update cmd to get the build output as an exec binary Co-authored-by: Sameen Karim <skarim@github.com> * Fix build command and errors.As usage per review feedback - go build ./... compiles but does not produce a binary. Changed to go build -o gh-stack . which actually outputs the executable. - errors.As(err, &ExitError{}) panics at runtime because the value type ExitError does not satisfy the error interface (only *ExitError does). Updated to the correct two-line pattern matching cmd/root.go. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Sameen Karim <skarim@github.com>
1.9 KiB
1.9 KiB
gh-stack: Copilot Instructions
A Go CLI extension (gh stack) for managing stacked branches and pull requests. Uses Cobra for commands, bubbletea/lipgloss for TUI, and stretchr/testify for tests.
Build and validate
go mod download # install deps
go build -o gh-stack . # build
go vet ./... # static analysis. Always run before tests.
go test -race -count=1 ./... # tests with race detection
No Makefile, no code generation, no external linter config. Standard Go toolchain only.
Project layout
cmd/: One Cobra command per file. Each exports<Name>Cmd(cfg *config.Config)with logic inrun<Name>().internal/git/:Opsinterface (52 methods) wrapping git CLI.MockOpsfor tests. Package-level functions delegate to swappableopsvariable.internal/github/:ClientOpsinterface (11 methods) for GitHub API.MockClientfor tests.internal/config/:Configstruct passed to all commands. Holds I/O, colors, and test hooks (SelectFn,ConfirmFn,InputFn,GitHubClientOverride).internal/stack/: Stack file (.git/gh-stack, JSON) management with file locking.internal/tui/: bubbletea views (stackview,modifyview).
Coding conventions
- Return typed
ExitErrorsentinels (codes 1-10 incmd/utils.go) fromRunE. Never callos.Exit()directly. - Check errors with
var exitErr *ExitError; errors.As(err, &exitErr). - Table-driven tests with
t.Run()subtests. - Use
config.NewTestConfig()for test configs with captured I/O. - Mock git:
restore := git.SetOps(&git.MockOps{...}); defer restore(). Always defer restore. - Mock GitHub:
cfg.GitHubClientOverride = &github.MockClient{...}. - Mock prompts: set
cfg.SelectFn,cfg.ConfirmFn, orcfg.InputFn. - Load stack files with
stack.Load(dir)after writing to get correct checksums.
For full architecture details, see AGENTS.md in the repository root.