Skip to content

AGENTS.md

Latest commit

 

History

History
129 lines (116 loc) · 7.06 KB

AGENTS.md

File metadata and controls

129 lines (116 loc) · 7.06 KB
Raw

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.