Skip to content

Latest commit

 

History

History
171 lines (130 loc) · 8.73 KB

CONTRIBUTING.md

File metadata and controls

171 lines (130 loc) · 8.73 KB

Contributing to agentx

Thanks for your interest in agentx. This guide covers how to report a problem, propose a change and get a pull request merged.

agentx is in early development, so commands, output and file formats still change. Open an issue before you start on anything larger than a small fix, so we can agree on the approach first.

Everyone taking part is expected to follow the Code of Conduct.

Set up your machine

You need:

  • Go 1.27 or later – the exact version is the go line in apps/cli/go.mod
  • git 2.40 or later
  • make
  • macOS or Linux

For the desktop app, you also need:

  • Node 26 or later – .node-version names it for version managers
  • pnpm 12 – the exact version is packageManager in the root package.json
  • Rust, and on Linux the WebKitGTK development packages; see the desktop app's README

Clone the repository:

git clone https://github.com/grundmanise/agentx.git
cd agentx

For the desktop app, install its dependencies from the repository root, then Playwright's Chromium once for its end-to-end tests:

pnpm install
pnpm --dir apps/desktop exec playwright install chromium

Find your way around

Path What it holds
apps/cli The Go module of the agentx command-line tool
apps/desktop The desktop app (Tauri and React); see its README
GLOSSARY.md The vocabulary: the terms to use in code, docs, issues and PRs
docs/adr Architecture decisions
docs/spec Contracts and specs, such as the CLI's output contract
docs/help-center The user documentation, built with Mintlify
scripts/install.sh, packaging The install script and the templates of the Homebrew cask and formula

Read the ADRs and specs that touch the area you're changing before you start.

Development commands

Run these from the repository root. Targets are named <action>-<app>. The CLI targets run against the Go module in apps/cli:

Target What it does Command
make fmt-cli Formats every Go file in place gofmt -w .
make fmt-check-cli Checks that every Go file is formatted, without changing any gofmt -l ., fails when any file is listed
make lint-cli Runs the linters, including go vet, with the project's configuration golangci-lint run ./... with apps/cli/.golangci.yml
make tidy-check-cli Checks that go.mod and go.sum list exactly the dependencies the code uses go mod tidy, fails when go.mod or go.sum change
make build-cli Compiles every package go build ./..., CGO_ENABLED=0 on Linux and 1 on macOS
make test-cli Runs every test with the race detector, never from cache go test -race -count=1 ./...
make check-cli Runs all the CLI checks CI runs, in the same order fmt-check-cli lint-cli tidy-check-cli build-cli test-cli
make check-desktop Runs all the desktop app checks CI runs: the frontend, then the Tauri shell pnpm install --frozen-lockfile, pnpm check, pnpm test, pnpm build, then cargo fmt --check and cargo clippy --locked -- -D warnings
make check Runs every check CI runs check-cli check-desktop

To run the tests without the race detector, as CI does on macOS, use make test-cli RACE=.

golangci-lint needs no install: its version is pinned in apps/cli/.golangci-lint-version, and make lint-cli builds that release into the build cache on first use through go run, locally and in CI alike. The build uses the Go version apps/cli/go.mod specifies.

make check-desktop needs the desktop tools listed in Set up your machine, including Playwright's Chromium. The desktop app's own commands, such as pnpm fix, are in its README.

Make a change

  • Use the vocabulary. Name concepts as GLOSSARY.md defines them, and avoid the synonyms it lists. If a concept you need is missing, raise it in your issue or PR.
  • Respect the ADRs. If your change contradicts an architecture decision, say so in the PR and explain why the decision should be reopened.
  • Test it. Commands are cobra commands, built in apps/cli/internal/cli/run.go. Tests drive cli.Run against a temporary home, so they never touch your real agent configurations. Add or update tests with every change in behavior.
  • Update the Help Center. When you add a feature or change how one works, update the matching page in docs/help-center. Keep it clear, structured and concise, in an imperative tone.
  • Run make check. It runs what CI runs: the CLI checks and the desktop app checks. A green make check means a green pull request. It needs the tools of both apps, so to check only the side you changed, run make check-cli or make check-desktop. Run make fmt-cli to fix Go formatting, and pnpm fix in apps/desktop to fix the desktop app's formatting and lint.

Open a pull request

  • Branch name: name the branch after the change in product terms, such as feat/source-removed-drift.
  • Title: use the Conventional Commits format, such as feat(skill): check managed skills for upstream updates. Pull requests are squash merged, so the title becomes the commit on main, and its type decides where the change appears in the release notes.
  • Description: in an imperative style, summarize what changed for users and why. Describe the implementation only where it's needed to understand the change. For how to write a good commit message, read How to Write a Git Commit Message; where its rules for the subject line differ, the Conventional Commits title above wins.
  • Evidence: if the change affects functionality or behavior, show it before and after with screenshots, a recording or, for an execution-based change, the console output. Otherwise, it's optional.
  • Writing style: don't use em dashes (—) anywhere; use en dashes (–), hyphens (-) or another suitable punctuation.

Keep each pull request to one change. A maintainer reviews it once CI is green.

Release notes

The release notes list the commits that change apps/cli or apps/desktop, by the type of their title:

Type Section
feat: a new command, flag or capability New
change: a change to how an existing feature behaves or reads Changes
perf, revert Changes
fix Fixes
docs, test, refactor, style, chore, ci Left out

A breaking change, marked ! after the type or with a BREAKING CHANGE: footer, is marked Breaking: in its section, and listed under Changes if its type is one that is left out, such as refactor!. The title's description becomes the entry, so write it for someone who uses agentx. Preview the notes with git-cliff: git cliff v0.1.0..main.

Open an issue

Search the existing issues first, then open one with a form:

  • Bug report: asks what you ran, what you expected, what happened instead, the output of agentx version and agentx doctor, your operating system and the agent clients involved.
  • Feature request: asks for the problem you want solved and the change you propose.
  • Something else: for a question, feedback, a documentation fix or anything else constructive.

New issues are labelled needs-triage until a maintainer looks at them.

Don't report a security vulnerability in a public issue. Report it privately instead, as the security policy describes.

Releases

agentx has two kinds of release:

  • Nightly: a prerelease of main, published once a day when the CLI or the desktop app changed and CI passed.
  • Stable: a maintainer starts it by hand, once a nightly has proved good enough. It promotes that nightly to a version such as v0.3.0.

Your merged change reaches users first in a nightly, then in the next stable release. To publish a release, see RELEASING.md.

License

agentx is licensed under the Apache License 2.0. By submitting a contribution, you agree that it's licensed under the same terms, as set out in section 5 of the license.