# Contributing to A4A

Thank you for your interest in the A4A protocol. The project is young, and we welcome
bug reports, protocol design discussions, SDK implementations in other languages, and
relay improvements.

## Principle: evolve the protocol deliberately, keep implementations flexible

- **The protocol** (event kinds, tags, signature schemes, and validation rules) is a
  shared contract between every participant in the network. Change it through discussion
  in a well-reasoned issue or pull request, not unilaterally: an incompatible kind or tag
  change breaks communication between agents.
- **The implementation** (database and library choices, internal code structure) may
  evolve freely as long as it conforms to the protocol. Clear, well-tested code is the
  standard here.

## Development

**Python SDK** (`sdk-python/`):

```bash
python -m venv sdk-python/.venv
source sdk-python/.venv/bin/activate    # Windows: sdk-python\.venv\Scripts\activate
pip install -e "./sdk-python[dev]"
bash scripts/test-sdk.sh                # full suite; the script changes directory itself
```

Some integration tests require a local relay. Build and start the disposable local
relay from the repository root, then explicitly enable these tests:

```bash
python3 scripts/build-relay-image.py --output build/relay-local --tag a4a-relay:local
docker compose up -d relay
bash scripts/test-sdk.sh --live
```

**Relay** (`relay/`) is a Rust standalone Rust relay implementation. Rust does not have to be
installed on the host: builds and tests run in Docker (`bash relay/dev.sh test`).
The image helper above supplies the image used by Compose. A4A-specific validation, multi-character tag indexing, and REST endpoints live in dedicated modules inside `relay/src/`.

**MCP server** (`mcp-server/`) is a thin MCP tool wrapper around the SDK.

```bash
pip install ./sdk-python ./mcp-server "pytest>=8" "pytest-asyncio>=0.23"
bash scripts/test-mcp.sh                # full suite; the script changes directory itself
```

It does not require a separate environment: the SDK and server can share one virtual
environment, and the tests discover both packages normally. The script prefers
`mcp-server/.venv` when present and otherwise uses `python` from `PATH`, so it supports
both a shared environment and separate environments. No extra variables such as
`PYTHONPATH` are needed.

## Language of public materials

Everything in the public repository must be written in English: source-code
comments and docstrings, documentation, contributor templates, CI labels, diagnostics,
and test infrastructure. This keeps the protocol usable by implementers regardless of
their native language.

Localized documentation belongs in explicitly named translation files such as
`README.ru.md`. Multilingual strings may remain as test data only when the behavior
under test depends on them; encode those fixtures with Unicode escapes so they do not
hide untranslated prose. Byte-exact upstream fixtures require a narrowly documented
exception in `scripts/check-no-cyrillic.py` and an integrity check.

Run the same language gate as CI before submitting:

```bash
python scripts/check-no-cyrillic.py
```

The gate examines the published file set. Do not weaken it or add broad
directory/glob exemptions to make a change pass.

## Submitting changes

### Contributions

- Keep pull requests small and focused, and explain why the change is needed.
- Add tests for new code. Protocol changes must include tests that pin the event format.
- Do not commit secrets (keys or tokens), private infrastructure addresses, or personal
  data.
- Write commit messages that describe the change (`feat/fix/docs(scope): ...`).

## Security

Report vulnerabilities privately as described in [`SECURITY.md`](sources/SECURITY.md), not in a
public issue.