Skip to content

chore: add AGENTS.md #375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
strantalis wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: add AGENTS.md #375

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Repository Guidelines

## Project Structure & Module Organization

- `xtest/`: Cross-client compatibility test harness (Python + `pytest`), with fixtures in `xtest/fixtures/` and golden data in `xtest/golden/`.
- `xtest/sdk/`: Helper scripts and Makefiles for checking out/building SDKs under test (e.g., `xtest/sdk/scripts/checkout-all.sh`, `cd xtest/sdk && make`).
- `vulnerability/`: Playwright-based security regression tests (`vulnerability/tests/`).
- `.github/workflows/`: CI workflows (lint/type-check, xtest matrix runs, vulnerability runs).

## Build, Test, and Development Commands

- Enter the dev environment: `devbox shell` (installs Python/JDK/Node per `devbox.json`).
- Install xtest deps: `python -m pip install -r xtest/requirements.txt`
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To improve the local development workflow, consider including the linting and type-checking tools in this installation step. This avoids reinstalling them every time the checks are run (as per the command on line 27) and centralizes dependency management.

Suggested change
- Install xtest deps: `python -m pip install -r xtest/requirements.txt`
- Install xtest deps & tools: `python -m pip install -r xtest/requirements.txt ruff black pyright`

- Run xtest: `cd xtest && pytest`
- Focus a subset: `pytest --sdks "go js" --focus go` (see `xtest/conftest.py` options)
- HTML report: `pytest --html tmp/test-report.html --self-contained-html`
- Build SDK CLIs (after checkout): `cd xtest/sdk && make`
- Run vulnerability tests: `cd vulnerability && npm ci && npm test` (requires a running platform; see `README.md` and `vulnerability/README.md`).

## Coding Style & Naming Conventions

- Python code in `xtest/` uses 4-space indentation, `snake_case`, and `pytest`-style fixtures.
- CI enforces these checks in `xtest/`:
- `ruff check`
- `black --check .`
- `pyright`
- Local equivalent: `cd xtest && python -m pip install -r requirements.txt && python -m pip install ruff black pyright && ruff check && black --check . && pyright`
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

If the linting tools are installed as part of the main dependency setup (as suggested for line 13), this command can be simplified to only run the checks. This makes the local check process faster and the command easier to read.

Suggested change
- Local equivalent: `cd xtest && python -m pip install -r requirements.txt && python -m pip install ruff black pyright && ruff check && black --check . && pyright`
- Local equivalent: `cd xtest && ruff check && black --check . && pyright`


## Testing Guidelines

- `pytest` tests live in `xtest/test_*.py`; add new fixtures under `xtest/fixtures/`.
- Tests assume a platform backend is reachable (Docker + Keycloak). Use `xtest/test.env` as a template:
- `cd xtest && set -a && source test.env && set +a`

## Commit & Pull Request Guidelines

- Use semantic commit/PR titles (enforced by CI): `feat(xtest): ...`, `fix(vulnerability): ...`, `docs: ...` (types: `fix|feat|chore|docs`; scopes include `xtest`, `vulnerability`, `go`, `java`, `web`, `ci`).
- DCO sign-off is required: `git commit -s -m "feat(xtest): ..."` (see `CONTRIBUTING.md`).
- PRs should include a clear description, linked issue (if any), and relevant logs/screenshots for test failures; reviewers are defined in `CODEOWNERS`.