Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (91 loc) · 5.48 KB

AGENTS.md

File metadata and controls

102 lines (91 loc) · 5.48 KB

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.