weblate Agent Skills & AI Rules

# 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 API behavior 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.
- Keep user-data export, the ``weblate_schemas`` user-data schema, and account
  settings import in sync. The export and schema should cover profile fields,
  including fields intentionally excluded from import; omit internal database
  identifiers and user relations. Validate uploads against the packaged schema
  and model or form rules; import portable settings only, never counters, audit
  history, credentials, or source account identifiers. Represent exported
  project and component references with slugs or slug paths, never database IDs.
- Do not add tests that duplicate OpenAPI schema expectations covered by the
  tracked snapshot in `docs/specs/openapi.yaml`; schema changes are visible
  during review. Allow focused tests of configuration-dependent behavior that
  the snapshot cannot cover, and parsing and validation of served schema
  documents without asserting fixed schema contents. Keep other tests focused
  on API behavior, permissions, validation, schema endpoint availability, and
  documentation UI integration.
- All translatable user-facing strings must use Django i18n helpers. New
  messages introduced exclusively for API responses must not be localized. API
  responses may reuse localized messages generated by code shared with the UI,
  including model, form, and validator errors. Do not disable localization,
  replace shared messages with API-specific English messages, or require
  separate UI/API messages solely to enforce nonlocalized API responses. Do not
  flag reuse of shared localized messages as a review issue.
- Messages written to persisted storage, such as the audit log, add-on log, or
  changes, should not be localized.
- Supply an explicit user when recording history changes. Automated operations
  must use the appropriate system or add-on bot user rather than `None`.
  Preserve the initiating user for settings changes and user-triggered creation,
  including queued work and pending file writes. Keep the initiating actor
  separate from the content author. Do not substitute a generic bot for a missing
  actor.
  Pass the anonymous user explicitly for intentional anonymous actions. Missing
  history users currently trigger error reporting and a `RuntimeWarning`, which
  pytest treats as an error. This is temporary soft enforcement in production,
  not permission to omit the actor. Do not suppress the warning to hide missing
  actors in tests; supply the correct user instead.
- Weblate does not maintain compatibility for queued Celery task messages across
  upgrades. Task signatures and payloads may change without legacy argument
  adapters. Do not flag incompatibility with messages published by an older
  release as a defect unless cross-version compatibility is explicitly required
  for the change. The requirement to preserve initiating users through queued
  work concerns actor attribution, not cross-version task compatibility.
- 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`. Include a concise commit
  body describing the motivation. When the commit resolves an issue, add a
  `Fixes #123` clause.
- Pin dependencies to exact versions using `==`. Use a non-exact constraint
  only when there is a deliberate reason, and document that reason next to the
  dependency declaration, as is done for `certifi` to allow newer certificate
  bundles.
- 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.
- Document every new configuration option. Document native Django settings in
  the appropriate settings documentation, typically `docs/admin/config.rst`,
  and Docker-exposed environment variables in
  `docs/admin/install/docker.rst`. Update both documentation surfaces when an
  option is available through both mechanisms.
- 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.
- Review `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.
- Review does not necessarily require an edit. Update the threat model in the
  same change only when its scope, actors, trust boundaries, assumptions,
  claimed security properties, or triage dispositions change or leave a gap,
  following its "Conditions that change this model" section. Features covered
  by existing guidance do not need individual entries. Keep feature-level
  endpoint, permission, configuration, implementation, and limit details in
  the relevant feature or administration documentation; link to them only when
  needed to explain a distinct boundary, exception, or triage outcome.
- 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

- Select test fixtures by their identifying fields or retain the object returned
  when creating them. Do not use an unordered queryset's first row when the
  assertion depends on which row was selected. Use an explicit `order_by()`
  when order is the behavior under test.
- Screenshot tests must explicitly configure the services and fixture data
  visible in the captured UI. Do not depend on configuration inherited from
  other tests or reusable database snapshots. Wait for asynchronous content to
  finish loading before capture, and avoid competing providers whose response
  order changes the rendered output.
- Complex data migrations must have populated upgrade tests in `ci/run-migrate`:
  add old-version setup and post-upgrade assertion scripts in
  `ci/migrate-scripts/`, gated to applicable source releases. Seed data that
  exercises conditional branches and cross-app relationships, and verify the
  resulting data, not just successful migration execution. Empty-database runs
  and helper tests against the latest schema do not detect missing migration
  dependencies or premature access to future columns. Use historical models
  from `apps.get_model()` and declare dependencies for the models accessed.
  Keep migration database access independent of current model helpers.
- For an isolated worktree environment, use the development container workflow
  in `docs/contributing/start.rst` (`devcontainer` section). Run
  `./scripts/devcontainer up`, then use `./scripts/devcontainer exec --` before
  the commands below. Run `./scripts/devcontainer doctor` to diagnose setup,
  and `./scripts/devcontainer bootstrap` after dependency changes. The test
  environment uses PostgreSQL and Valkey; it does not start application workers.
- 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`. If tests cannot reach the configured
  PostgreSQL server, do not assume it is stopped: local sandboxing can block
  access to an already-running service. Retry with permission to access the
  local service when sandboxing is the cause. Only when PostgreSQL is confirmed
  not to be running, and it is installed as a local Linux service, try
  `sudo service postgresql start` and rerun the failed command. Treat service
  startup as a recovery step, not a prerequisite for every test invocation. If
  you start PostgreSQL this way, stop it with `sudo service postgresql stop`
  after the retry, whether the command succeeds or fails, so no service process
  is left running when the task finishes.
- 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.