weblate

# 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.
- Use human-readable Ruff rule names in overrides, such as
  `# ruff: ignore[assert]`; do not use or rewrite them to cryptic codes such as
  `# noqa: S102`, `# ruff: N801`, or `# ruff: noqa: F841`.
- 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.
- Add new user-configurable model fields to the existing REST serializers, API
  documentation, schema, and tests for that model. Review write permissions and
  validation explicitly. Keep secrets, computed state, and intentionally
  internal fields unexposed, and document the reason when the omission is not
  self-evident.
- All user-facing strings must be translatable using Django i18n helpers, except
  messages used in the API or persisted storage, such as the audit log, add-on
  log, or changes; these messages should not be localized.
- 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. In
  `docs/snippets/`, do not hand-edit content inside autogenerated marker
  blocks; manual explanatory text outside those blocks is preserved by the
  generator and can be edited when appropriate.

## 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.

## GitHub discussions

- GitHub organization discussion URLs such as
  `https://github.com/orgs/WeblateOrg/discussions/19794` can still belong to the
  `WeblateOrg/weblate` repository. When working with these URLs, resolve the
  discussion through `WeblateOrg/weblate` repository discussions instead of
  treating the URL as an issue, pull request, or organization-only object.
- Use GitHub discussion-aware tooling, such as `gh api graphql` against
  `repository(owner: "WeblateOrg", name: "weblate") { discussion(number: ...) }`,
  when the regular GitHub issue or pull request connectors do not expose the
  discussion.

## 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.
- Prefer `prek` for Ruff checks and formatting; `uv run ruff ...` is not
  guaranteed to work in this environment because Ruff can be provided only
  through the pre-commit hook environment.
- 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.