mirror of
https://gh.wpcy.net/https://github.com/WeblateOrg/weblate.git
synced 2026-04-25 01:22:24 +08:00
86 lines
4.3 KiB
Markdown
86 lines
4.3 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.
|
|
|
|
## 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 `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.
|
