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