1# Contributing to zot
2
3Contributions are welcome, including bug reports, design feedback, documentation, tests, and code. This guide explains what makes a contribution easy to evaluate and safe to merge.
4
5## Choose the right starting point
6
7### Reporting a defect
8
9Use the bug-report template and provide enough information for someone else to reproduce the problem:
10
11- the output of `zot --version`
12- operating system and terminal
13- provider and model, when relevant
14- the smallest sequence of actions that triggers the problem
15- expected and actual results
16- relevant logs with credentials and private session content removed
17
18Search existing issues first. If the behavior only occurs with a particular provider, include the HTTP status and sanitized response details when available, but never post an API key, OAuth token, authorization header, or full private transcript.
19
20### Suggesting a capability
21
22Start with the feature-request template. Describe the workflow that is difficult today before proposing an interface. Useful proposals explain:
23
24- who encounters the problem
25- why existing flags, extensions, or configuration do not solve it
26- how the new behavior would appear in the CLI, TUI, SDK, or protocol
27- compatibility or migration concerns
28- reasonable alternatives
29
30For changes that introduce a public API, alter stored data, modify an extension protocol, or span several packages, wait for design feedback before investing in an implementation.
31
32### Small corrections
33
34Focused typo, documentation, and test improvements can usually go directly to a pull request. Keep them separate from behavioral changes.
35
36## Design boundaries
37
38zot is intended to remain a lightweight, single-binary application. A contribution should fit that direction rather than increasing scope by default.
39
40The major ownership boundaries are:
41
42- `packages/core`: provider-independent agent behavior and session structures
43- `packages/provider`: provider requests, streaming responses, model discovery, retries, and wire-specific behavior
44- `packages/provider/auth`: credential and login handling
45- `packages/agent`: command-line orchestration, configuration, runtime assembly, RPC, and zotfiles
46- `packages/agent/modes`: interactive and non-interactive user modes
47- `packages/agent/extensions`, `extproto`, and `ext`: extension hosting, protocol, and SDK
48- `packages/agent/skills`: reusable instruction discovery
49- `packages/agent/swarm`: background-agent supervision and state
50- `packages/agent/tools`: built-in tools, permissions, and jail checks
51- `packages/tui`: terminal mechanics and rendering
52- `packages/ignore`: ignore matching
53
54Keep provider-specific decisions out of the core agent loop. Keep terminal rendering out of orchestration code. If a feature can be delivered cleanly as an extension, consider that before expanding the built-in surface.
55
56New dependencies need a clear benefit. The standard library and current dependency set are preferred, particularly for functionality that would otherwise increase binary size or complicate cross-platform builds.
57
58## Preparing a development checkout
59
60Use the Go version declared in `go.mod`, then build from the repository root:
61
62```sh
63go mod download
64make build
65./bin/zot --version
66```
67
68Useful commands:
69
70```sh
71make build       # compile ./bin/zot
72make run         # build and start the interactive application
73make test        # run all tests with the race detector
74make lint        # run go vet and verify gofmt
75```
76
77Tests must not depend on real provider credentials, paid model calls, a developer's global zot state, or a specific terminal. Use local HTTP test servers, fixtures, temporary directories, and synthetic credentials.
78
79## Making a change
80
81A reviewable change has one purpose. Avoid bundling renames, formatting churn, generated metadata updates, or unrelated refactors into the same pull request.
82
83For a bug fix:
84
851. Demonstrate the failure with a focused test when practical.
862. Find the package where the invalid state first appears.
873. Fix that layer rather than compensating in the UI or another downstream consumer.
884. Exercise neighboring cases that use the same parser, event path, or persisted format.
89
90For new behavior:
91
921. Identify every user-visible and integration surface involved.
932. Preserve existing configuration, sessions, RPC clients, and extensions unless a breaking change has been agreed upon.
943. Add tests in the package that owns the behavior.
954. Update the relevant documentation in the same pull request.
96
97Follow ordinary Go conventions. Format changed Go files with `gofmt`, propagate cancellation through `context.Context`, and wrap errors with useful operational context. Error messages and logs must not expose credentials or private content.
98
99The repository's `AGENTS.md` contains additional implementation guidance for automated tools and is also useful as an architecture reference for human contributors.
100
101## Areas requiring additional checks
102
103### Providers and models
104
105Provider contributions should cover request serialization, successful parsing, streamed events, API errors, and cancellation using local fixtures or an `httptest` server. Confirm model identifiers, context and output limits, reasoning support, provider routing, and pricing data from authoritative sources.
106
107Do not treat all OpenAI-compatible endpoints as interchangeable. Service-specific behavior belongs in `packages/provider` and should be represented by tests.
108
109### Sessions and event streams
110
111Changes to messages or events must preserve valid tool-call and tool-result sequences. Check persistence and replay, not only live output. Consider resume, compaction, import, export, and forks whenever a shared session representation changes.
112
113### RPC and extensions
114
115The RPC and extension schemas are consumed outside this repository. Prefer additive changes, define behavior when a peer omits a new field, and keep protocol stdout free of human diagnostics. Update `docs/rpc.md` or `docs/extensions.md` for contract changes.
116
117### Permissions and jail behavior
118
119Permission failures must deny the operation. Test path traversal, symlink resolution, and cancellation where applicable. Jail mode is a safety guardrail rather than a hard isolation boundary, and contributions must preserve that distinction.
120
121### Operating systems and terminals
122
123CI runs on Linux, macOS, and Windows. Process handling, signals, shell invocation, filesystem paths, clipboard access, resize behavior, and terminal input often have platform-specific implementations. Inspect all build-tagged variants and avoid assumptions about Unix paths or ANSI support.
124
125## Verification
126
127Run focused package tests while developing. Before opening a pull request that changes Go code, run:
128
129```sh
130gofmt -w <changed-go-files>
131go vet ./...
132go test -race ./...
133git diff --check
134```
135
136`make lint` and `make test` provide the repository equivalents for the lint and test steps.
137
138Documentation-only pull requests do not need the Go suite unless they modify executable examples or generated content. They should still be checked for accurate commands, links, and formatting.
139
140If a validation command cannot pass because of an unrelated repository or environment problem, describe the exact command and failure in the pull request. Do not silently omit it.
141
142## Pull request shape
143
144Open the pull request against `main` and include:
145
146- the problem being addressed
147- the chosen solution and why it belongs in zot
148- tests added or updated
149- commands used for verification
150- user-visible, compatibility, and platform effects
151- a linked issue when one exists
152
153Keep commits understandable and use concise, imperative subjects. Update your branch normally when review requests changes. Do not force-push over review history unless there is a specific reason and reviewers have been informed.
154
155A reviewer may ask for a contribution to be reduced in scope, moved to a different package, implemented as an extension, or split into independent pull requests. This is intended to keep behavior maintainable and does not diminish the underlying use case.
156
157## Documentation locations
158
159Choose the document that owns the public surface:
160
161- `README.md` for installation, authentication, flags, common commands, modes, and user workflows
162- `docs/providers.md` for provider-specific setup and behavior
163- `docs/rpc.md` for the embedding protocol
164- `docs/extensions.md` for extension authors
165- `docs/skills.md` for reusable skills
166- `docs/themes.md` for theme files
167- `docs/zotfiles.md` for portable agents
168
169Examples should be runnable and limitations should be stated directly.
170
171## Sensitive security reports
172
173Do not open a public issue containing an exploitable vulnerability, live credential, or private user data. Use GitHub's private vulnerability reporting for this repository when available. Include a minimal reproduction, affected versions, impact, and any suggested mitigation without using production secrets.
174
175## License
176
177By submitting a contribution, you agree that it may be distributed under the repository's [MIT License](LICENSE).