weblate/AGENTS.md

# Agents guidance for Weblate

This file captures agent-specific guidance for working in the Weblate codebase.
For application-developer workflows and broader product integration guidance, use
`docs/devel/` instead of repeating that material here.

## Project overview

- Weblate is a Django-based web translation platform with Celery background
  tasks.
- The primary stack is Python, Django, JavaScript, and HTML/CSS/Bootstrap.

## Code expectations

- Follow existing Django patterns and project conventions.
- Prefer the repository's configured Ruff-based formatting and linting rules.
- Prefer type hints and use `from __future__ import annotations` in Python
  modules.
- Use `TYPE_CHECKING` imports for type-only dependencies when that avoids
  runtime import cycles.
- All user-facing strings must be translatable using Django i18n helpers.
- In templates, use `{% translate %}` / `{% blocktranslate %}` for translatable
  text.
- Preserve accessibility and the existing Bootstrap/jQuery-based frontend
  patterns. For user-facing HTML, CSS, or JavaScript changes, follow
  `ACCESSIBILITY.md` and `docs/contributing/frontend.rst`, including keyboard
  navigation, visible focus, semantic controls, labels/errors, and
  non-color-only state.
- Write commit messages using the Conventional Commits format
  `<type>(<optional scope>): <description>`. Common types include `feat`,
  `fix`, `docs`, `refactor`, `test`, `ci`, and `chore`. Example:
  `fix(translations): handle empty component slug`.
- Keep new project code under GPL-3.0-or-later and include the repository's
  usual copyright and SPDX license header in new Python files.

## Documentation expectations

- Match the style of the surrounding page in `docs/`; prefer clear, direct,
  instructional prose with short paragraphs over marketing language or large
  rewrites.
- Preserve the existing structure and heading hierarchy. Prefer extending an
  existing section over creating a new one, and keep headings in sentence case
  to match the current documentation.
- Use Sphinx and reStructuredText conventions already present in the docs:
  prefer semantic cross-references such as `:ref:`, `:doc:`, `:guilabel:`,
  `:setting:`, `:wladmin:`, `:file:`, and `:program:` instead of raw links,
  repeated explanations, or ad-hoc formatting.
- Keep documentation changes scoped and additive when possible. Avoid
  unnecessary rewrites or structure changes, especially because the
  documentation is translated.
- Use admonitions, screenshots, and code blocks only when they add concrete
  value and match the style of the surrounding page.
- Keep manually maintained explanations in the main documentation pages and do
  not hand-edit autogenerated snippets in `docs/snippets/`.

## Weblate-specific guardrails

- Be careful with repository, webhook, and file-handling code; validate inputs
  and avoid introducing path traversal, command injection, or script injection
  risks.
- Handle VCS operations defensively and surface failures cleanly.
- Mock external VCS operations and API calls in tests.
- Check `docs/security/threat-model.rst` when changing public endpoints,
  authentication or token modes, deployment modes, backup or import formats, VCS
  execution paths, outbound integration classes, add-on execution capabilities,
  or security-relevant defaults for hooks, HTTPS, rate limits, CSP,
  private-network access, or backup import limits.
- Update `docs/security/threat-model.rst` in the same change when the threat
  model's "Conditions that change this model" apply, including when unsupported
  components become supported product surface, claimed security properties
  change, or a vulnerability report exposes a model gap.
- For user-visible changes, add or update a changelog entry in the top section
  of `docs/changes.rst` for the upcoming release.
- Do not alter changelog sections for already released versions; put follow-up
  entries in the current unreleased section instead.
- Keep changelog entries concise and link to the relevant documentation for the
  feature instead of embedding long explanations in the changelog itself.
- Minor fixes and fixes for features that have not been released yet do not
  need a changelog entry.

## Testing and linting instructions

- Install the development dependencies first using
  `uv sync --all-extras --dev`.
- After syncing, prefer `uv run ...` for subsequent commands so they use the
  virtual environment created in `.venv`. If needed, you can also activate it
  with `source .venv/bin/activate` or invoke tools from `.venv/bin/`.
- Prefer `uv run prek run --all-files` as the primary linting/formatting command because
  it runs the repository's configured pre-commit framework checks.
- `prek` is a third-party reimplementation of the `pre-commit` tool.
- Use `pytest` to run the test suite: `uv run pytest`. On a fresh checkout,
  first follow the local test setup in `docs/contributing/tests.rst`
  (`DJANGO_SETTINGS_MODULE=weblate.settings_test`, `collectstatic`, and test
  database prerequisites). `scripts/test-database.sh` can be sourced to set up
  the database connection variables such as `CI_DB_USER`, `CI_DB_PASSWORD`,
  `CI_DB_HOST`, and `CI_DB_PORT`.
- Use `pylint` to lint the Python code: `uv run pylint weblate/ scripts/`
- Use `mypy` to type check with the same command as CI:
  `uv run mypy --show-column-numbers weblate scripts/*.py ./*.py | ./scripts/filter-mypy.sh`.
- New or changed code should not introduce new mypy failures where current
  Django typing support makes that practical. Existing non-enforced mypy
  findings should not be worsened.