# Custom review instructions for GitLab Duo Code Review. # Spec: https://docs.gitlab.com/user/duo_agent_platform/customize/review_instructions/ # # When updating: keep rules concrete and grep-able. Reference helpers by # their package + name (for example, `cmdutils.NewEnumValue`, # `cmdtest.SetupCmdForTest`) rather than vague guidance like "follow the # canonical pattern". Inlined rule text is used verbatim by Duo; file # references get summarized. instructions: # ============================================================ # GENERAL GO CODE # ============================================================ - name: Error handling fileFilters: - '**/*.go' instructions: | Most basics here are enforced by `errcheck`, `errorlint`, and `staticcheck ST1005` in `.golangci.yml`. The rules below are the project-specific judgments those linters can't make. 1. For `cmd.Flags().MarkRequired(...)` / `MarkFlagsMutuallyExclusive(...)` and similar cobra calls that return an error, use `cobra.CheckErr(err)` rather than `_ = ...`. 2. When a function has a primary error and a deferred cleanup error (e.g., `defer file.Close()`), combine them with `errors.Join(primary, cleanupErr)`. Do not print one and return the other; that splits the failure across surfaces. 3. For deferred cleanup that must affect the returned error, use a named return value and a closure: ```go func doThing() (err error) { f, err := os.Open(...) if err != nil { return err } defer func() { err = errors.Join(err, f.Close()) }() ... } ``` 4. When a function returns `(value, error)`, do not silently convert a sentinel error into `return nil, nil`. Distinguish "not found" from "real error" via an explicit sentinel (e.g., `errors.Is(err, ErrNotFound)`) or by documenting the contract. Quiet `(nil, nil)` on a sentinel hides bugs at the call site. 5. Do not silently fall back to a default value or behavior when an error occurs. Surface the error (return it, or log via the `internal/dbg` package); let the caller choose the fallback. Eating the error and substituting a default is a debugging dead-end. - name: Go idioms (Go 1.26+) fileFilters: - '**/*.go' instructions: | The project is on Go 1.26+. The `modernize` linter enforces `any`, `slices.*`, `strings.Cut*`, and similar Go 1.21+ idioms, and `gocritic` (diagnostic + style tags) enforces many of the rest. The remaining project-specific judgments: 1. Prefer `new(literalValue)` over `gitlab.Ptr(literalValue)` or intermediate variables for pointer-to-literal. For example, write `new(true)` rather than `gitlab.Ptr(true)`. Background: client-go 3.0 deprecates `gitlab.Ptr`. 2. Replace long `if / else if / else if` chains over the same value with a `switch` statement. Enforced by `gocritic`'s `ifElseChain`; prefer `switch` here over the inverted-guard style, which applies to a long block gated by one condition. 3. Use `map[K]struct{}` (not `map[K]bool`) for set-membership data structures — less allocation, clearer intent. 4. Prefer `iter.Seq` / `iter.Seq2` range-over-func iterators (Go 1.23+) for paged or generator-style traversals where they're available. 5. Compile regular expressions once at package scope (`var fooRe = regexp.MustCompile(...)`), not inside the hot path of a function. - name: Naming fileFilters: - '**/*.go' instructions: | 1. Names describe the value, not the code that produced it. If a function no longer needs full `iostreams.IOStreams` and only writes, rename the parameter to `out io.Writer`. If a parameter's role changes, rename it. 2. When a function has a side effect (creating files, mutating state), the name should reflect it. Split `ConfigFile()` (read-only) from `EnsureConfigFile()` (creates if missing). 3. New command sub-packages export a single constructor named `NewCmd`, not `NewCmdList` / `NewCmdGet` / etc. — the package name already carries the verb. 4. Avoid identifier names that only differ from existing ones by suffix (e.g., `projectAccessTokenResponseJson` next to `projectAccessTokenResponse`). Pick a name that distinguishes the role. 5. Unexport types, constants, and functions that are not used outside their package. Public API surface is a maintenance commitment. 6. When introducing a helper, field, or option that parallels a standard-library API (especially `net/http`), mirror the stdlib name. Example: a helper that derives an HTTP proxy URL from glab's config is named `ProxyFromConfig` (parallel to `http.ProxyFromEnvironment`), the struct field is `proxy` (parallel to `http.Transport.Proxy`), the client option is `WithProxy`. Don't bake the protocol into a name when the field is protocol-agnostic (e.g., a generic proxy config key should be `proxy`, not `https_proxy`). - name: Code reuse and dead code fileFilters: - '**/*.go' instructions: | Dead code, unused fields, and unused parameters are enforced by `unused` and `unparam` in `.golangci.yml`. The remaining rules are project-specific code-reuse judgments. 1. Before adding a new helper, search the codebase for existing equivalents. Common locations: `internal/cmdutils/`, `internal/iostreams/`, `internal/testing/cmdtest/`, `internal/api/`, `internal/glrepo/`, `internal/tableprinter/`, `internal/text/`. **Reuse, do not re-derive.** 2. If a new function substantially duplicates an existing one (bulk vs. single-item operations, paired endpoint builders), refactor: call the single-item function in a loop, or extract a shared helper. 3. Tests that don't make a meaningful assertion (e.g., construct a value and check `assert.NotNil`) must either be strengthened to test behavior or removed. `assert.True(t, true)` placeholders are not acceptable. 4. Function signatures should accept only the values they actually use. If a helper only needs `note.Position`, take `*gitlab.NotePosition`, not `*gitlab.Note`. Avoid passing `cmdutils.Factory` into helpers — pass the resolved `glrepo.Interface` / `*gitlab.Client` / branch string directly. 5. Prefer returning parsed/typed values (e.g., `*url.URL`, `time.Duration`) over strings that the caller must re-parse. The parser belongs next to the producer. 6. Inline single-use, single-line helpers at the call site unless the helper carries a meaningful name. A two-statement helper called from one place is rarely worth the indirection. 7. For ANSI-color stripping in tests, use `github.com/acarl005/stripansi` (already a project dep) — see `internal/commands/schedule/list/list_test.go`. Don't hand-roll regex stripping. - name: Comments fileFilters: - '**/*.go' instructions: | `scripts/comment-overlap` rejects comments whose every word is already carried by the adjacent code, and `gocritic`'s `commentedOutCode` rejects commented-out code. Do not re-flag either. Those gates are deliberately conservative and leave two gaps worth reviewing: 1. Partial restatement passes the gate. A comment only has to add one word the code lacks to survive it, so `// Trim whitespace from the line first` above `line = strings.TrimSpace(line)` still ships. Document only what a competent Go reader cannot infer from the code, and delete a restating comment rather than rewording it. 2. Godoc length is unenforced. `staticcheck` ST1020-ST1022 check the form of a doc comment, nothing checks whether it earns its lines, and doc comments are the larger share of comment volume in this repo. Keep godoc to what the name and signature do not convey. In both cases the test is whether the comment carries *why* — a non-obvious constraint, an ordering requirement, an upstream bug being worked around, a rejected alternative. Prose narrating *what* the code does is the common failure. - name: Control flow fileFilters: - '**/*.go' instructions: | 1. Prefer inverted-guard / early-return style: when a long block is gated by a single condition, flip it to `if !cond { return ... }` so the happy path is unindented. 2. Declare variables as close to their use as possible. Don't pre-declare at function top when only an inner block needs them. 3. Thread `context.Context` from `cmd.Context()` through every function that calls into the GitLab client or another context-aware API. Pass it via `gitlab.WithContext(ctx)` to client-go methods. Never drop the context partway down the call chain. # ============================================================ # COMMANDS # ============================================================ - name: Command structure fileFilters: - 'internal/commands/**/*.go' - '!**/*_test.go' instructions: | New (sub-)commands under `internal/commands/**` must follow the "Command Structure" pattern in `CONTRIBUTING.md:185-195`: 1. Each (sub-)command is in its own package. The file where the cobra command is defined is named the same as the package. 2. The command is created by a factory function named `NewCmd` (no package-name suffix like `NewCmdList`) that takes a single argument: the `cmdutils.Factory`. 3. Define an unexported `options` struct (just `options`, not `xxxOptions`) inside the package. Methods and fields on `options` are not exported. Optional constructor named `newOptions`. 4. In `NewCmd`, instantiate `opts := &options{...}` and pre-assign factory dependencies onto the struct: `io: f.IO()`, `baseRepo: f.BaseRepo`, `gitlabClient: f.GitLabClient`, etc. 5. Create the cobra command in a local `cmd` variable. 6. If multiple flags are added, retrieve `cmd.Flags()` once into a local `fl` variable and use `fl` for all registrations. 7. Split logic into three methods on `*options`: - `complete(cmd *cobra.Command, args []string) error` — populate `opts` from CLI input. - `validate() error` — validate the completed options beyond what cobra can enforce. - `run(ctx context.Context) error` — execute the business logic. Only implement the methods you actually need. 8. The `cobra.Command.RunE` calls `complete` → `validate` → `run` and passes `cmd.Context()` to `run`. **No business logic, validation, or API calls in `RunE` itself.** 9. Commands must never read from or write to `os.Stdin/Stdout/Stderr` directly. Always go through `opts.io` (an `*iostreams.IOStreams` assigned from `f.IO()`). 10. If a needed seam is missing on `cmdutils.Factory` (e.g., for subprocess execution), add it to the factory rather than introducing a package-level `var foo = func(...)` shim. The factory exists to provide test seams cleanly. Canonical reference: `internal/commands/gpg-key/get/get.go`. - name: Command documentation fileFilters: - 'internal/commands/**/*.go' - '!**/*_test.go' instructions: | CLI documentation is generated from Go source files by `make gen-docs`. The following rules apply to the documentation fields of `cobra.Command` definitions. Short description (`Short` field): 1. Write in the imperative mood. For example: `Create a new merge request.` 2. End with a period. 3. Do not duplicate the command name. 4. For experimental commands, append `(EXPERIMENTAL)`. Synopsis (`Long` field): 5. All new commands must include a `Long` field. 6. Do not repeat information already in the `Short` field. 7. Use lists for multiple constraints, input types, or behavioral differences. 8. If the command requires a minimum GitLab version, state it. For example: `This command requires GitLab 17.0 or later.` 9. **Do not reference underlying REST or GraphQL endpoint paths in user-facing `Long` text.** Describe what the user gets, not how it's implemented. Internals leak into docs and rot. 10. Document environment variables via the `cobra.Command.Annotations` map (key: `help:environment`), not inside `Long`. 11. Write each paragraph in `Long` as one source line. Cobra emits `Long` verbatim, so hard-wrapped source stays hard-wrapped in the terminal — the terminal then re-wraps around the source breaks, producing orphan fragments. Bullets, section headers, and `Example` lines are exempt. Usage line / positional arguments (`Use` field): 12. Format positional arguments with these conventions: - Required: `` (e.g., `glab mr view `). - Optional: `[]` (e.g., `glab ci trace []`). - One of several, required: `` (e.g., `glab mr checkout `). - One of several, optional: `[]` (e.g., `glab mr note list []`). Experimental and beta features: 13. Use `text.ExperimentalString` or `text.BetaString` from `internal/text/text.go`. Do not copy these strings manually. 14. When only a flag is experimental, prepend `(EXPERIMENTAL)` to its description and add a note in `Long` explaining feature flag requirements. Examples (`Example` field): 15. Every command must include at least one realistic example. Do not use examples that only repeat the command syntax. 16. Examples live on the leaf command they apply to, not on parent group commands. 17. Annotate examples with an inline comment using `# Comment text` above the command. Lead with the simplest realistic invocation and annotate even that one — explicit beats implicit for users scanning `--help`. 18. For commands with many options, show the most common combinations first. 19. Use `heredoc.Doc(\`...\`)` (from `github.com/MakeNowJust/heredoc/v2`) for multi-line `Long` and `Example` content. Indent with tabs (the heredoc package strips them). Never build these fields by concatenating quoted literals with embedded `\n`: ```go Long: "First line.\n\n" + "Second line.", ``` Error and log messages are out of scope. 20. A heredoc block is a Go raw string, so it cannot contain a backtick or an escape sequence — a literal `\n` renders as the two characters `\` and `n`. If the content needs either, use `heredoc.Docf` with `%[1]s` in place of each backtick and `` "`" `` as the final argument: ```go Long: heredoc.Docf(` Use %[1]s--foo%[1]s to enable foo. `, "`"), ``` Reference: `internal/commands/mr/note/mr_note_create.go`. Flag descriptions: 21. Start each flag description with a capital letter and end with a period. 22. Use angle-bracket placeholders for user-supplied values: ``, ``, ``. 23. Do not manually annotate boolean flag defaults. pflag automatically appends `(default true)` for boolean flags whose default is `true`. Do not add it manually. No default annotation is required for boolean flags whose default is `false`; do not add `(default false)`. 24. Use standard metavars for common value types: `username` for a username, `string` for a branch name / file path / output format, `int` for an integer ID. 25. For output-format flags, use `-F, --output [text | json]` as the canonical form. 26. For slice flags (`StringSliceVar`, `Int64SliceVar`, etc.), include the phrase: `Multiple can be comma-separated or specified by repeating the flag.` Use `StringArrayVar` if comma-separation should NOT be supported. 27. Do not use `-v` as a shorthand for anything — it collides with `--verbose` and `--version` conventions. - name: Help text sources fileFilters: - 'internal/**/*.go' - '!**/*_test.go' instructions: | 1. Do not embed help text from a sidecar `.md` file with `//go:embed`. Inline the content in the Go source via `heredoc.Doc`. Sidecar files bypass the CI markdown lint glob and split help text across two files without a corresponding readability win. `make check-embed` enforces this. - name: Bundled skills fileFilters: - 'internal/commands/**/*.go' - 'internal/commands/skills/bundled/assets/**/SKILL.md' - '!**/*_test.go' instructions: | Bundled agent skills live in `internal/commands/skills/bundled/assets/`: - `glab-stack/SKILL.md` covers `internal/commands/stack/**`. - `glab/SKILL.md` covers general command usage across `glab`. When an MR changes a command's user-visible contract, check whether the matching `SKILL.md` still describes it correctly. A contract change is any of: the command's `Use` or arguments, a flag that is added, renamed, or removed, a new or removed TTY requirement, prompt, or editor, or new required follow-up steps. If the skill now gives instructions that would fail, hang, or leave work unfinished, and the MR does not update that `SKILL.md`, ask for the skill to be updated in the same MR. If the MR does update the skill, check that each command it shows doesn't reach a prompt, editor, or TTY check with the flags shown. Do not flag internal refactors, test-only changes, or help-text wording changes. When an MR edits a `SKILL.md`, with or without code changes, check for what `TestBundledSkillsUseRealCommandsAndFlags` can't see: flags that become required under certain conditions, and follow-up steps the command needs before the work is finished. That test already checks that every command and flag the skill mentions exists. - name: Flag handling fileFilters: - 'internal/commands/**/*.go' - '!**/*_test.go' instructions: | 1. Prefer cobra's built-in flag/argument helpers over manual checks: - `cmd.MarkFlagsMutuallyExclusive("a", "b")` instead of hand-rolled `if foo != "" && bar != "" { return error }`. - `cmd.MarkFlagsRequiredTogether("a", "b")`. - `cmd.MarkFlagsOneRequired("a", "b")` when at least one is required. - `cmd.MarkFlagRequired("flag")`. - `Args: cobra.ExactArgs(N)` / `cobra.NoArgs` / `cobra.RangeArgs(...)` instead of manual `len(args) != N` checks in `RunE`/`complete`. For commands that take no positional arguments, use `cobra.NoArgs`, never `cobra.ExactArgs(0)` — `NoArgs` names the unexpected argument in its error. Enforced by `make check-args`. 2. For closed-set string flags, use `cmdutils.NewEnumValue(allowedValues, defaultValue)` from `internal/cmdutils/enum_flag.go`. Do not validate the string by hand in `complete`/`validate`. 3. Use typed cobra flag variants where available: `Int64Var`, `BoolVar`, `TimeVar`, etc. Do not parse times/numbers from `StringVar` by hand. 4. To target a project, use `cmdutils.EnableRepoOverride(cmd, f)` from `internal/cmdutils/repo_override.go` (`-R/--repo`). Do not invent a custom `--project` flag. 5. For group-scoped commands, use `cmdutils.GroupOverride`. 6. When `-R`, `--group`, and `--instance` coexist, mark them mutually exclusive: `cmd.MarkFlagsMutuallyExclusive("repo", "group", "instance")`. 7. Required flags are often a "bad" UX choice — prefer the first positional argument when there's a clear primary subject (e.g., the token ID, the runner ID). 8. To detect whether a flag was explicitly set by the user (vs. left at its default), use `cmd.Flags().Changed("")`. Do not infer "unset" by comparing the bound value to its default — that breaks when the user explicitly passes the default value, and it makes the "no flag" case impossible to distinguish from "flag = default". - name: IO streams and output fileFilters: - 'internal/commands/**/*.go' - '!**/*_test.go' instructions: | The rules below are the project-specific output conventions. 1. For JSON output, use `opts.io.PrintJSON(v)` from `internal/iostreams/print_json.go`. `PrintJSON` handles `--jq` filtering and the nil-slice-to-`[]` normalization. 2. To register the canonical `-F/--output [text | json]` flag plus `--jq`, use `cmdutils.EnableJSONOutput(cmd)` from `internal/cmdutils/output_format.go`. Do not invent a separate `--json` boolean. 3. **JSON output is for machines, not humans.** Do not pretty-print or wrap it. Users can pipe to `jq` themselves. 4. For table output, use `internal/tableprinter` (`NewTablePrinter()`, `AddRow(...)`, `String()`, `SetIsTTY(...)`). 5. For interactive prompts, use the helpers on `IOStreams`: `Confirm`, `Input`, `Select`, `MultiSelect`, `Password`, `Multiline`, `Editor`, `DirectEditor`. Do not hand-roll `fmt.Scanln` confirmation loops. Check `io.PromptEnabled()` / `io.IsInteractive()` before prompting so `NO_PROMPT` and non-TTY users are respected. 6. For terminal hyperlinks, use `io.Hyperlink(displayText, targetURL)`. - name: API client and pagination fileFilters: - 'internal/**/*.go' instructions: | 1. For commands tied to one repo, use `f.GitLabClient()`. For multi-repo operations, use `f.ApiClient(host)`. Don't construct `*gitlab.Client` directly in command code. 2. For unauthenticated flows (e.g., release-note fetching), use `api.NewClientFromConfig(host, config.NewBlankConfig(), ...)`. Do not drop down to `net/http` or `http.Get` for GitLab endpoints — even for downloads, prefer the `gitlab.Client`. 3. Pass `gitlab.WithContext(ctx)` (from `cmd.Context()`) to every client-go call. This is non-optional. 4. For paginated list endpoints, use `gitlab.ScanAndCollect` (or `gitlab.Scan2` iterators). Do not hand-roll `for page := 1;` loops. See `internal/cmdutils/cmdutils.go:92` for the canonical pattern. 5. For HTTP status checks, use `resp.HasStatusCode(http.StatusXxx)` — never compare integers like `resp.StatusCode == 200`. Always use `http.Status*` constants over magic numbers. - name: Package layering fileFilters: - 'internal/commands/**/*.go' - '!**/*_test.go' instructions: | 1. API-shape concerns belong in an `api` (sub-)package, not in command packages or `utils` packages. GraphQL queries, REST endpoint construction, response struct definitions, case normalization for API enums — these go in `internal/api/` or a command-local `api/` subpackage. 2. Command packages should focus on CLI surface: flag parsing, prompts, output formatting, calling into the api layer. 3. Do not import one command package from another. Shared command-level utilities go in `internal/cmdutils/` (or a new shared package), not a sibling command. 4. Helpers that take `io *iostreams.IOStreams` should put it as the first parameter to mirror the standard-library convention of `io.Writer`- first. - name: Config and environment fileFilters: - 'internal/**/*.go' instructions: | 1. New configuration keys (global or per-host) are declared in `KeySchema` in `internal/config/schema.go` as a `KeyDef` entry. The schema drives the blank config, `config set` validation, defaults, env-var resolution, legacy aliases, and keyring eligibility — do not read settings ad-hoc from disk or env. 2. Set `KeyDef.EnvVars` to declare environment variables that override a key (the uppercase form of the key name is the default when EnvVars is empty). Do not call `os.LookupEnv` / `os.Getenv` in command code for settings that have, or should have, a config-file equivalent. 3. Document environment variables on the `cobra.Command.Annotations` map (key: `help:environment`), not in free-form `Long` text — that placement is also surfaced in generated docs. - name: Deprecations fileFilters: - 'internal/**/*.go' instructions: | 1. When deprecating a flag with `cmd.Flags().MarkDeprecated(...)`, write the message as a sentence continuation: Cobra prepends `Flag -- has been deprecated, ` (ending in a comma), so start your message with a lowercase letter and end with a period. For example, `use --output instead.` renders as `Flag --output-format has been deprecated, use --output instead.`. 2. When the deprecated flag has a direct replacement, end the message with `use -- instead.`. When there is no replacement, describe the resulting behavior. For example, `tracking is enabled by default.`. 3. Avoid time-relative words like `now` or `currently` in deprecation messages. 4. When deprecating an environment variable, update the `help:environment` annotation in `root.go`: remove the deprecated entry, add the replacement with a full description, keep all entries in alphabetical order, and mirror the change in the README's environment variables section. # ============================================================ # TESTS # ============================================================ - name: Test setup fileFilters: - 'internal/**/*_test.go' instructions: | 1. Use `cmdtest.SetupCmdForTest(t, NewCmd, parseFlags, opts...)` from `internal/testing/cmdtest/factory.go` to set up command tests. It returns a `CmdExecFunc` you can call with the command's args. 2. Configure test state with `FactoryOption`s — see `internal/testing/cmdtest/factory.go` for the full list: `WithStdin`, `WithBranch`, `WithBaseRepo`, `WithGitLabClient`, `WithApiClient`, `WithBuildInfo`, `WithExecutor`, `WithGitRunner`, `WithConsole`, etc. 3. **If you need a seam that isn't there, add a new `FactoryOption` to `cmdtest`** — do not hand-roll factory wiring inline in the test, and do not introduce a package-level `var xxx = func(...)` shim in production code to be overridden by the test. 4. For GitLab API mocking, use the client-go testing package: `gitlabtesting "gitlab.com/gitlab-org/api/client-go/v3/testing"`. ```go tc := gitlabtesting.NewTestClient(t) tc.MockUsers.EXPECT().GetGPGKey(int64(123)).Return(testKey, nil, nil) exec := cmdtest.SetupCmdForTest(t, NewCmd, false, cmdtest.WithGitLabClient(tc.Client)) ``` **Do not introduce new `httpmock`-based HTTP responders** for code paths that go through client-go. Migrate existing HTTP mocks when touching files in the same package. 5. For mock call ordering, use `gomock.InOrder(...)`. 6. Canonical reference: `internal/commands/gpg-key/get/get_test.go`; JSON-assertion pattern: `internal/commands/runnercontroller/token/list/list_test.go`. - name: Test discipline fileFilters: - 'internal/**/*_test.go' instructions: | Many test discipline basics are enforced by linters in `.golangci.yml`: `testifylint` (use testify, `require` before indexing, `assert.Empty` over `assert.Equal(t, "", ...)`, no `require` in HTTP handlers), `tparallel` (`t.Parallel`), `usetesting` (`t.TempDir` / `t.Chdir` / `t.Setenv`). The rules below are the project-specific judgments those linters can't make. 1. New behavior gated by a flag, argument shape, or branch must include a test for each meaningful path — including the "no flag set", "invalid input", and "default" branches. A new `--` must not ship without an exercising test. 2. When asserting on a command's JSON output, `json.Unmarshal` into a typed struct and assert on fields. Do not substring-match on the raw JSON text (`assert.Contains(out, '"id": 1')`). Reference: `internal/commands/runnercontroller/token/list/list_test.go`. 3. **Test the user-visible behavior of the command**, not the configuration plumbing or internal field assignments. If a test constructs `options{}` directly and checks a field, it probably should drive the command through `cmdtest.SetupCmdForTest` instead. 4. Prefer flat per-case assertions over loops. `for _, tc := range testCases { tc.run() }` is fine for table-driven tests with shared setup, but don't loop over a slice just to assert each element — spell out the asserts (`assert.Equal(t, tokens[0].ID, results[0].ID)`, `assert.Equal(t, tokens[1].ID, results[1].ID)`) so failures point at the specific element. 5. When adding a flag-aware test variant, keep the original no-flag test as well. Do not rename / repurpose existing baseline tests — that quietly removes coverage. Add new tests alongside, don't replace. 6. When adding behavior to one of a set of parallel sibling commands (e.g., `token list` for project / group / personal tokens), add the equivalent test in each sibling package — otherwise coverage drifts asymmetrically. 7. `cmdtest.SetupCmdForTest` produces non-TTY IOStreams by default. Don't reach for `t.Setenv("NO_COLOR", ...)` or other TTY-affecting env hacks — if you need different behavior, pass a `FactoryOption` (`cmdtest.WithIOStreamsOverride` or similar) rather than mutating process environment. 8. Prefer test-local fixtures over package-level `var` blocks unless the fixture is genuinely shared by multiple tests. Local fixtures make ownership and lifetime obvious. # ============================================================ # SHELL SCRIPTS # ============================================================ - name: Shell scripts fileFilters: - 'scripts/**/*.sh' - '*.sh' instructions: | 1. Write usage messages and error output to stderr: `echo "..." >&2`. User-consumable program output goes to stdout; diagnostics go to stderr. 2. Use a direct shebang (`#!/usr/bin/env bash` or `#!/bin/sh`) and make the script executable. Do not invoke scripts with `bash ./script.sh` from other scripts or CI config — call the script directly. 3. Validate required environment variables explicitly at the top of the script (e.g., `: "${APPSTORE_CONNECT_API_KEY_FILE:?must be set}"`). A surprising `:` mount or missing var should error early, not silently. 4. Use `set -euo pipefail` for new scripts. # ============================================================ # PROJECT-LEVEL / DEPENDENCIES # ============================================================ - name: Dependencies fileFilters: - 'go.mod' - 'go.sum' instructions: | 1. Before adding a new third-party dependency, check whether the standard library or an existing dependency covers the need. For example, prefer `os.UserConfigDir` over `github.com/adrg/xdg`. 2. New dependencies must be justified in the MR description: what the stdlib can't do and why an existing dep won't suffice. 3. Unexpected `go.mod` / `go.sum` changes that don't trace to a deliberate need should be removed or explained. - name: Tool versions fileFilters: - '.tool-versions' - 'Makefile' - '.gitlab-ci.yml' instructions: | 1. The project pins developer tools via `mise` and `.tool-versions`. The Makefile reads the golangci-lint version from `.tool-versions`. When bumping golangci-lint, also update the `lint` job image tag in `.gitlab-ci.yml` so local and CI environments stay aligned. 2. New developer tools should be added to `.tool-versions` (not to the Makefile alone).