mirror of
https://gh.wpcy.net/https://github.com/WeblateOrg/weblate.git
synced 2026-04-26 09:34:56 +08:00
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 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`.
|
|
- Include the GPL-3.0-or-later license header in new Python files.
|
|
|
|
## 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 a changelog entry to the top section of
|
|
`docs/changes.rst`.
|
|
|
|
## 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 `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: `pytest weblate`. 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: `pylint weblate/`
|
|
- Use `mypy` to type check the code: `mypy weblate/`
|
|
- All mentioned linting tools MUST pass.
|
