{"owner":"WeblateOrg","repo":"weblate","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":2852,"categories":["root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Agents guidance for Weblate\n\nThis file captures agent-specific guidance for working in the Weblate codebase.\nFor application-developer workflows and broader product integration guidance, use\n`docs/devel/` instead of repeating that material here.\n\n## Project overview\n\n- Weblate is a Django-based web translation platform with Celery background\n  tasks.\n- The primary stack is Python, Django, JavaScript, and HTML/CSS/Bootstrap.\n\n## Code expectations\n\n- Follow existing Django patterns and project conventions.\n- Prefer the repository's configured Ruff-based formatting and linting rules.\n- Use human-readable Ruff rule names in overrides, such as\n  `# ruff: ignore[assert]`; do not use or rewrite them to cryptic codes such as\n  `# noqa: S102`, `# ruff: N801`, or `# ruff: noqa: F841`.\n- Prefer type hints and use `from __future__ import annotations` in Python\n  modules.\n- Use `TYPE_CHECKING` imports for type-only dependencies when that avoids\n  runtime import cycles.\n- Add new user-configurable model fields to the existing REST serializers, API\n  documentation, schema, and API behavior tests for that model. Review write\n  permissions and validation explicitly. Keep secrets, computed state, and\n  intentionally internal fields unexposed, and document the reason when the\n  omission is not self-evident.\n- Keep user-data export, the ``weblate_schemas`` user-data schema, and account\n  settings import in sync. The export and schema should cover profile fields,\n  including fields intentionally excluded from import; omit internal database\n  identifiers and user relations. Validate uploads against the packaged schema\n  and model or form rules; import portable settings only, never counters, audit\n  history, credentials, or source account identifiers. Represent exported\n  project and component references with slugs or slug paths, never database IDs.\n- Do not add tests that duplicate OpenAPI schema expectations covered by the\n  tracked snapshot in `docs/specs/openapi.yaml`; schema changes are visible\n  during review. Allow focused tests of configuration-dependent behavior that\n  the snapshot cannot cover, and parsing and validation of served schema\n  documents without asserting fixed schema contents. Keep other tests focused\n  on API behavior, permissions, validation, schema endpoint availability, and\n  documentation UI integration.\n- All translatable user-facing strings must use Django i18n helpers. New\n  messages introduced exclusively for API responses must not be localized. API\n  responses may reuse localized messages generated by code shared with the UI,\n  including model, form, and validator errors. Do not disable localization,\n  replace shared messages with API-specific English messages, or require\n  separate UI/API messages solely to enforce nonlocalized API responses. Do not\n  flag reuse of shared localized messages as a review issue.\n- Messages written to persisted storage, such as the audit log, add-on log, or\n  changes, should not be localized.\n- Supply an explicit user when recording history changes. Automated operations\n  must use the appropriate system or add-on bot user rather than `None`.\n  Preserve the initiating user for settings changes and user-triggered creation,\n  including queued work and pending file writes. Keep the initiating actor\n  separate from the content author. Do not substitute a generic bot for a missing\n  actor.\n  Pass the anonymous user explicitly for intentional anonymous actions. Missing\n  history users currently trigger error reporting and a `RuntimeWarning`, which\n  pytest treats as an error. This is temporary soft enforcement in production,\n  not permission to omit the actor. Do not suppress the warning to hide missing\n  actors in tests; supply the correct user instead.\n- Weblate does not maintain compatibility for queued Celery task messages across\n  upgrades. Task signatures and payloads may change without legacy argument\n  adapters. Do not flag incompatibility with messages published by an older\n  release as a defect unless cross-version compatibility is explicitly required\n  for the change. The requirement to preserve initiating users through queued\n  work concerns actor attribution, not cross-version task compatibility.\n- In templates, use `{% translate %}` / `{% blocktranslate %}` for translatable\n  text.\n- Preserve accessibility and the existing Bootstrap/jQuery-based frontend\n  patterns. For user-facing HTML, CSS, or JavaScript changes, follow\n  `ACCESSIBILITY.md` and `docs/contributing/frontend.rst`, including keyboard\n  navigation, visible focus, semantic controls, labels/errors, and\n  non-color-only state.\n- Write commit messages using the Conventional Commits format\n  `<type>(<optional scope>): <description>`. Common types include `feat`,\n  `fix`, `docs`, `refactor`, `test`, `ci`, and `chore`. Example:\n  `fix(translations): handle empty component slug`. Include a concise commit\n  body describing the motivation. When the commit resolves an issue, add a\n  `Fixes #123` clause.\n- Pin dependencies to exact versions using `==`. Use a non-exact constraint\n  only when there is a deliberate reason, and document that reason next to the\n  dependency declaration, as is done for `certifi` to allow newer certificate\n  bundles.\n- Keep new project code under GPL-3.0-or-later and include the repository's\n  usual copyright and SPDX license header in new Python files.\n\n## Documentation expectations\n\n- Match the style of the surrounding page in `docs/`; prefer clear, direct,\n  instructional prose with short paragraphs over marketing language or large\n  rewrites.\n- Preserve the existing structure and heading hierarchy. Prefer extending an\n  existing section over creating a new one, and keep headings in sentence case\n  to match the current documentation.\n- Use Sphinx and reStructuredText conventions already present in the docs:\n  prefer semantic cross-references such as `:ref:`, `:doc:`, `:guilabel:`,\n  `:setting:`, `:wladmin:`, `:file:`, and `:program:` instead of raw links,\n  repeated explanations, or ad-hoc formatting.\n- Keep documentation changes scoped and additive when possible. Avoid\n  unnecessary rewrites or structure changes, especially because the\n  documentation is translated.\n- Document every new configuration option. Document native Django settings in\n  the appropriate settings documentation, typically `docs/admin/config.rst`,\n  and Docker-exposed environment variables in\n  `docs/admin/install/docker.rst`. Update both documentation surfaces when an\n  option is available through both mechanisms.\n- Use admonitions, screenshots, and code blocks only when they add concrete\n  value and match the style of the surrounding page.\n- Keep manually maintained explanations in the main documentation pages. In\n  `docs/snippets/`, do not hand-edit content inside autogenerated marker\n  blocks; manual explanatory text outside those blocks is preserved by the\n  generator and can be edited when appropriate.\n\n## Weblate-specific guardrails\n\n- Be careful with repository, webhook, and file-handling code; validate inputs\n  and avoid introducing path traversal, command injection, or script injection\n  risks.\n- Handle VCS operations defensively and surface failures cleanly.\n- Mock external VCS operations and API calls in tests.\n- Review `docs/security/threat-model.rst` when changing public endpoints,\n  authentication or token modes, deployment modes, backup or import formats, VCS\n  execution paths, outbound integration classes, add-on execution capabilities,\n  or security-relevant defaults for hooks, HTTPS, rate limits, CSP,\n  private-network access, or backup import limits.\n- Review does not necessarily require an edit. Update the threat model in the\n  same change only when its scope, actors, trust boundaries, assumptions,\n  claimed security properties, or triage dispositions change or leave a gap,\n  following its \"Conditions that change this model\" section. Features covered\n  by existing guidance do not need individual entries. Keep feature-level\n  endpoint, permission, configuration, implementation, and limit details in\n  the relevant feature or administration documentation; link to them only when\n  needed to explain a distinct boundary, exception, or triage outcome.\n- For user-visible changes, add or update a changelog entry in the top section\n  of `docs/changes.rst` for the upcoming release.\n- Do not alter changelog sections for already released versions; put follow-up\n  entries in the current unreleased section instead.\n- Keep changelog entries concise and link to the relevant documentation for the\n  feature instead of embedding long explanations in the changelog itself.\n- Minor fixes and fixes for features that have not been released yet do not\n  need a changelog entry.\n\n## GitHub discussions\n\n- GitHub organization discussion URLs such as\n  `https://github.com/orgs/WeblateOrg/discussions/19794` can still belong to the\n  `WeblateOrg/weblate` repository. When working with these URLs, resolve the\n  discussion through `WeblateOrg/weblate` repository discussions instead of\n  treating the URL as an issue, pull request, or organization-only object.\n- Use GitHub discussion-aware tooling, such as `gh api graphql` against\n  `repository(owner: \"WeblateOrg\", name: \"weblate\") { discussion(number: ...) }`,\n  when the regular GitHub issue or pull request connectors do not expose the\n  discussion.\n\n## Testing and linting instructions\n\n- Select test fixtures by their identifying fields or retain the object returned\n  when creating them. Do not use an unordered queryset's first row when the\n  assertion depends on which row was selected. Use an explicit `order_by()`\n  when order is the behavior under test.\n- Screenshot tests must explicitly configure the services and fixture data\n  visible in the captured UI. Do not depend on configuration inherited from\n  other tests or reusable database snapshots. Wait for asynchronous content to\n  finish loading before capture, and avoid competing providers whose response\n  order changes the rendered output.\n- Complex data migrations must have populated upgrade tests in `ci/run-migrate`:\n  add old-version setup and post-upgrade assertion scripts in\n  `ci/migrate-scripts/`, gated to applicable source releases. Seed data that\n  exercises conditional branches and cross-app relationships, and verify the\n  resulting data, not just successful migration execution. Empty-database runs\n  and helper tests against the latest schema do not detect missing migration\n  dependencies or premature access to future columns. Use historical models\n  from `apps.get_model()` and declare dependencies for the models accessed.\n  Keep migration database access independent of current model helpers.\n- For an isolated worktree environment, use the development container workflow\n  in `docs/contributing/start.rst` (`devcontainer` section). Run\n  `./scripts/devcontainer up`, then use `./scripts/devcontainer exec --` before\n  the commands below. Run `./scripts/devcontainer doctor` to diagnose setup,\n  and `./scripts/devcontainer bootstrap` after dependency changes. The test\n  environment uses PostgreSQL and Valkey; it does not start application workers.\n- Install the development dependencies first using\n  `uv sync --all-extras --dev`.\n- After syncing, prefer `uv run ...` for subsequent commands so they use the\n  virtual environment created in `.venv`. If needed, you can also activate it\n  with `source .venv/bin/activate` or invoke tools from `.venv/bin/`.\n- Prefer `uv run prek run --all-files` as the primary linting/formatting command because\n  it runs the repository's configured pre-commit framework checks.\n- `prek` is a third-party reimplementation of the `pre-commit` tool.\n- Prefer `prek` for Ruff checks and formatting; `uv run ruff ...` is not\n  guaranteed to work in this environment because Ruff can be provided only\n  through the pre-commit hook environment.\n- Use `pytest` to run the test suite: `uv run pytest`. On a fresh checkout,\n  first follow the local test setup in `docs/contributing/tests.rst`\n  (`DJANGO_SETTINGS_MODULE=weblate.settings_test`, `collectstatic`, and test\n  database prerequisites). `scripts/test-database.sh` can be sourced to set up\n  the database connection variables such as `CI_DB_USER`, `CI_DB_PASSWORD`,\n  `CI_DB_HOST`, and `CI_DB_PORT`. If tests cannot reach the configured\n  PostgreSQL server, do not assume it is stopped: local sandboxing can block\n  access to an already-running service. Retry with permission to access the\n  local service when sandboxing is the cause. Only when PostgreSQL is confirmed\n  not to be running, and it is installed as a local Linux service, try\n  `sudo service postgresql start` and rerun the failed command. Treat service\n  startup as a recovery step, not a prerequisite for every test invocation. If\n  you start PostgreSQL this way, stop it with `sudo service postgresql stop`\n  after the retry, whether the command succeeds or fails, so no service process\n  is left running when the task finishes.\n- Use `pylint` to lint the Python code: `uv run pylint weblate/ scripts/`\n- Use `mypy` to type check with the same command as CI:\n  `uv run mypy --show-column-numbers weblate scripts/*.py ./*.py | ./scripts/filter-mypy.sh`.\n- New or changed code should not introduce new mypy failures where current\n  Django typing support makes that practical. Existing non-enforced mypy\n  findings should not be worsened.\n"},"files":{"AGENTS.md":"# Agents guidance for Weblate\n\nThis file captures agent-specific guidance for working in the Weblate codebase.\nFor application-developer workflows and broader product integration guidance, use\n`docs/devel/` instead of repeating that material here.\n\n## Project overview\n\n- Weblate is a Django-based web translation platform with Celery background\n  tasks.\n- The primary stack is Python, Django, JavaScript, and HTML/CSS/Bootstrap.\n\n## Code expectations\n\n- Follow existing Django patterns and project conventions.\n- Prefer the repository's configured Ruff-based formatting and linting rules.\n- Use human-readable Ruff rule names in overrides, such as\n  `# ruff: ignore[assert]`; do not use or rewrite them to cryptic codes such as\n  `# noqa: S102`, `# ruff: N801`, or `# ruff: noqa: F841`.\n- Prefer type hints and use `from __future__ import annotations` in Python\n  modules.\n- Use `TYPE_CHECKING` imports for type-only dependencies when that avoids\n  runtime import cycles.\n- Add new user-configurable model fields to the existing REST serializers, API\n  documentation, schema, and API behavior tests for that model. Review write\n  permissions and validation explicitly. Keep secrets, computed state, and\n  intentionally internal fields unexposed, and document the reason when the\n  omission is not self-evident.\n- Keep user-data export, the ``weblate_schemas`` user-data schema, and account\n  settings import in sync. The export and schema should cover profile fields,\n  including fields intentionally excluded from import; omit internal database\n  identifiers and user relations. Validate uploads against the packaged schema\n  and model or form rules; import portable settings only, never counters, audit\n  history, credentials, or source account identifiers. Represent exported\n  project and component references with slugs or slug paths, never database IDs.\n- Do not add tests that duplicate OpenAPI schema expectations covered by the\n  tracked snapshot in `docs/specs/openapi.yaml`; schema changes are visible\n  during review. Allow focused tests of configuration-dependent behavior that\n  the snapshot cannot cover, and parsing and validation of served schema\n  documents without asserting fixed schema contents. Keep other tests focused\n  on API behavior, permissions, validation, schema endpoint availability, and\n  documentation UI integration.\n- All translatable user-facing strings must use Django i18n helpers. New\n  messages introduced exclusively for API responses must not be localized. API\n  responses may reuse localized messages generated by code shared with the UI,\n  including model, form, and validator errors. Do not disable localization,\n  replace shared messages with API-specific English messages, or require\n  separate UI/API messages solely to enforce nonlocalized API responses. Do not\n  flag reuse of shared localized messages as a review issue.\n- Messages written to persisted storage, such as the audit log, add-on log, or\n  changes, should not be localized.\n- Supply an explicit user when recording history changes. Automated operations\n  must use the appropriate system or add-on bot user rather than `None`.\n  Preserve the initiating user for settings changes and user-triggered creation,\n  including queued work and pending file writes. Keep the initiating actor\n  separate from the content author. Do not substitute a generic bot for a missing\n  actor.\n  Pass the anonymous user explicitly for intentional anonymous actions. Missing\n  history users currently trigger error reporting and a `RuntimeWarning`, which\n  pytest treats as an error. This is temporary soft enforcement in production,\n  not permission to omit the actor. Do not suppress the warning to hide missing\n  actors in tests; supply the correct user instead.\n- Weblate does not maintain compatibility for queued Celery task messages across\n  upgrades. Task signatures and payloads may change without legacy argument\n  adapters. Do not flag incompatibility with messages published by an older\n  release as a defect unless cross-version compatibility is explicitly required\n  for the change. The requirement to preserve initiating users through queued\n  work concerns actor attribution, not cross-version task compatibility.\n- In templates, use `{% translate %}` / `{% blocktranslate %}` for translatable\n  text.\n- Preserve accessibility and the existing Bootstrap/jQuery-based frontend\n  patterns. For user-facing HTML, CSS, or JavaScript changes, follow\n  `ACCESSIBILITY.md` and `docs/contributing/frontend.rst`, including keyboard\n  navigation, visible focus, semantic controls, labels/errors, and\n  non-color-only state.\n- Write commit messages using the Conventional Commits format\n  `<type>(<optional scope>): <description>`. Common types include `feat`,\n  `fix`, `docs`, `refactor`, `test`, `ci`, and `chore`. Example:\n  `fix(translations): handle empty component slug`. Include a concise commit\n  body describing the motivation. When the commit resolves an issue, add a\n  `Fixes #123` clause.\n- Pin dependencies to exact versions using `==`. Use a non-exact constraint\n  only when there is a deliberate reason, and document that reason next to the\n  dependency declaration, as is done for `certifi` to allow newer certificate\n  bundles.\n- Keep new project code under GPL-3.0-or-later and include the repository's\n  usual copyright and SPDX license header in new Python files.\n\n## Documentation expectations\n\n- Match the style of the surrounding page in `docs/`; prefer clear, direct,\n  instructional prose with short paragraphs over marketing language or large\n  rewrites.\n- Preserve the existing structure and heading hierarchy. Prefer extending an\n  existing section over creating a new one, and keep headings in sentence case\n  to match the current documentation.\n- Use Sphinx and reStructuredText conventions already present in the docs:\n  prefer semantic cross-references such as `:ref:`, `:doc:`, `:guilabel:`,\n  `:setting:`, `:wladmin:`, `:file:`, and `:program:` instead of raw links,\n  repeated explanations, or ad-hoc formatting.\n- Keep documentation changes scoped and additive when possible. Avoid\n  unnecessary rewrites or structure changes, especially because the\n  documentation is translated.\n- Document every new configuration option. Document native Django settings in\n  the appropriate settings documentation, typically `docs/admin/config.rst`,\n  and Docker-exposed environment variables in\n  `docs/admin/install/docker.rst`. Update both documentation surfaces when an\n  option is available through both mechanisms.\n- Use admonitions, screenshots, and code blocks only when they add concrete\n  value and match the style of the surrounding page.\n- Keep manually maintained explanations in the main documentation pages. In\n  `docs/snippets/`, do not hand-edit content inside autogenerated marker\n  blocks; manual explanatory text outside those blocks is preserved by the\n  generator and can be edited when appropriate.\n\n## Weblate-specific guardrails\n\n- Be careful with repository, webhook, and file-handling code; validate inputs\n  and avoid introducing path traversal, command injection, or script injection\n  risks.\n- Handle VCS operations defensively and surface failures cleanly.\n- Mock external VCS operations and API calls in tests.\n- Review `docs/security/threat-model.rst` when changing public endpoints,\n  authentication or token modes, deployment modes, backup or import formats, VCS\n  execution paths, outbound integration classes, add-on execution capabilities,\n  or security-relevant defaults for hooks, HTTPS, rate limits, CSP,\n  private-network access, or backup import limits.\n- Review does not necessarily require an edit. Update the threat model in the\n  same change only when its scope, actors, trust boundaries, assumptions,\n  claimed security properties, or triage dispositions change or leave a gap,\n  following its \"Conditions that change this model\" section. Features covered\n  by existing guidance do not need individual entries. Keep feature-level\n  endpoint, permission, configuration, implementation, and limit details in\n  the relevant feature or administration documentation; link to them only when\n  needed to explain a distinct boundary, exception, or triage outcome.\n- For user-visible changes, add or update a changelog entry in the top section\n  of `docs/changes.rst` for the upcoming release.\n- Do not alter changelog sections for already released versions; put follow-up\n  entries in the current unreleased section instead.\n- Keep changelog entries concise and link to the relevant documentation for the\n  feature instead of embedding long explanations in the changelog itself.\n- Minor fixes and fixes for features that have not been released yet do not\n  need a changelog entry.\n\n## GitHub discussions\n\n- GitHub organization discussion URLs such as\n  `https://github.com/orgs/WeblateOrg/discussions/19794` can still belong to the\n  `WeblateOrg/weblate` repository. When working with these URLs, resolve the\n  discussion through `WeblateOrg/weblate` repository discussions instead of\n  treating the URL as an issue, pull request, or organization-only object.\n- Use GitHub discussion-aware tooling, such as `gh api graphql` against\n  `repository(owner: \"WeblateOrg\", name: \"weblate\") { discussion(number: ...) }`,\n  when the regular GitHub issue or pull request connectors do not expose the\n  discussion.\n\n## Testing and linting instructions\n\n- Select test fixtures by their identifying fields or retain the object returned\n  when creating them. Do not use an unordered queryset's first row when the\n  assertion depends on which row was selected. Use an explicit `order_by()`\n  when order is the behavior under test.\n- Screenshot tests must explicitly configure the services and fixture data\n  visible in the captured UI. Do not depend on configuration inherited from\n  other tests or reusable database snapshots. Wait for asynchronous content to\n  finish loading before capture, and avoid competing providers whose response\n  order changes the rendered output.\n- Complex data migrations must have populated upgrade tests in `ci/run-migrate`:\n  add old-version setup and post-upgrade assertion scripts in\n  `ci/migrate-scripts/`, gated to applicable source releases. Seed data that\n  exercises conditional branches and cross-app relationships, and verify the\n  resulting data, not just successful migration execution. Empty-database runs\n  and helper tests against the latest schema do not detect missing migration\n  dependencies or premature access to future columns. Use historical models\n  from `apps.get_model()` and declare dependencies for the models accessed.\n  Keep migration database access independent of current model helpers.\n- For an isolated worktree environment, use the development container workflow\n  in `docs/contributing/start.rst` (`devcontainer` section). Run\n  `./scripts/devcontainer up`, then use `./scripts/devcontainer exec --` before\n  the commands below. Run `./scripts/devcontainer doctor` to diagnose setup,\n  and `./scripts/devcontainer bootstrap` after dependency changes. The test\n  environment uses PostgreSQL and Valkey; it does not start application workers.\n- Install the development dependencies first using\n  `uv sync --all-extras --dev`.\n- After syncing, prefer `uv run ...` for subsequent commands so they use the\n  virtual environment created in `.venv`. If needed, you can also activate it\n  with `source .venv/bin/activate` or invoke tools from `.venv/bin/`.\n- Prefer `uv run prek run --all-files` as the primary linting/formatting command because\n  it runs the repository's configured pre-commit framework checks.\n- `prek` is a third-party reimplementation of the `pre-commit` tool.\n- Prefer `prek` for Ruff checks and formatting; `uv run ruff ...` is not\n  guaranteed to work in this environment because Ruff can be provided only\n  through the pre-commit hook environment.\n- Use `pytest` to run the test suite: `uv run pytest`. On a fresh checkout,\n  first follow the local test setup in `docs/contributing/tests.rst`\n  (`DJANGO_SETTINGS_MODULE=weblate.settings_test`, `collectstatic`, and test\n  database prerequisites). `scripts/test-database.sh` can be sourced to set up\n  the database connection variables such as `CI_DB_USER`, `CI_DB_PASSWORD`,\n  `CI_DB_HOST`, and `CI_DB_PORT`. If tests cannot reach the configured\n  PostgreSQL server, do not assume it is stopped: local sandboxing can block\n  access to an already-running service. Retry with permission to access the\n  local service when sandboxing is the cause. Only when PostgreSQL is confirmed\n  not to be running, and it is installed as a local Linux service, try\n  `sudo service postgresql start` and rerun the failed command. Treat service\n  startup as a recovery step, not a prerequisite for every test invocation. If\n  you start PostgreSQL this way, stop it with `sudo service postgresql stop`\n  after the retry, whether the command succeeds or fails, so no service process\n  is left running when the task finishes.\n- Use `pylint` to lint the Python code: `uv run pylint weblate/ scripts/`\n- Use `mypy` to type check with the same command as CI:\n  `uv run mypy --show-column-numbers weblate scripts/*.py ./*.py | ./scripts/filter-mypy.sh`.\n- New or changed code should not introduce new mypy failures where current\n  Django typing support makes that practical. Existing non-enforced mypy\n  findings should not be worsened.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/WeblateOrg/weblate/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Agents guidance for Weblate\n\nThis file captures agent-specific guidance for working in the Weblate codebase.\nFor application-developer workflows and broader product integration guidance, use\n`docs/devel/` instead of repeating that material here.\n\n## Project overview\n\n- Weblate is a Django-based web translation platform with Celery background\n  tasks.\n- The primary stack is Python, Django, JavaScript, and HTML/CSS/Bootstrap.\n\n## Code expectations\n\n- Follow existing Django patterns and project conventions.\n- Prefer the repository's configured Ruff-based formatting and linting rules.\n- Use human-readable Ruff rule names in overrides, such as\n  `# ruff: ignore[assert]`; do not use or rewrite them to cryptic codes such as\n  `# noqa: S102`, `# ruff: N801`, or `# ruff: noqa: F841`.\n- Prefer type hints and use `from __future__ import annotations` in Python\n  modules.\n- Use `TYPE_CHECKING` imports for type-only dependencies when that avoids\n  runtime import cycles.\n- Add new user-configurable model fields to the existing REST serializers, API\n  documentation, schema, and API behavior tests for that model. Review write\n  permissions and validation explicitly. Keep secrets, computed state, and\n  intentionally internal fields unexposed, and document the reason when the\n  omission is not self-evident.\n- Keep user-data export, the ``weblate_schemas`` user-data schema, and account\n  settings import in sync. The export and schema should cover profile fields,\n  including fields intentionally excluded from import; omit internal database\n  identifiers and user relations. Validate uploads against the packaged schema\n  and model or form rules; import portable settings only, never counters, audit\n  history, credentials, or source account identifiers. Represent exported\n  project and component references with slugs or slug paths, never database IDs.\n- Do not add tests that duplicate OpenAPI schema expectations covered by the\n  tracked snapshot in `docs/specs/openapi.yaml`; schema changes are visible\n  during review. Allow focused tests of configuration-dependent behavior that\n  the snapshot cannot cover, and parsing and validation of served schema\n  documents without asserting fixed schema contents. Keep other tests focused\n  on API behavior, permissions, validation, schema endpoint availability, and\n  documentation UI integration.\n- All translatable user-facing strings must use Django i18n helpers. New\n  messages introduced exclusively for API responses must not be localized. API\n  responses may reuse localized messages generated by code shared with the UI,\n  including model, form, and validator errors. Do not disable localization,\n  replace shared messages with API-specific English messages, or require\n  separate UI/API messages solely to enforce nonlocalized API responses. Do not\n  flag reuse of shared localized messages as a review issue.\n- Messages written to persisted storage, such as the audit log, add-on log, or\n  changes, should not be localized.\n- Supply an explicit user when recording history changes. Automated operations\n  must use the appropriate system or add-on bot user rather than `None`.\n  Preserve the initiating user for settings changes and user-triggered creation,\n  including queued work and pending file writes. Keep the initiating actor\n  separate from the content author. Do not substitute a generic bot for a missing\n  actor.\n  Pass the anonymous user explicitly for intentional anonymous actions. Missing\n  history users currently trigger error reporting and a `RuntimeWarning`, which\n  pytest treats as an error. This is temporary soft enforcement in production,\n  not permission to omit the actor. Do not suppress the warning to hide missing\n  actors in tests; supply the correct user instead.\n- Weblate does not maintain compatibility for queued Celery task messages across\n  upgrades. Task signatures and payloads may change without legacy argument\n  adapters. Do not flag incompatibility with messages published by an older\n  release as a defect unless cross-version compatibility is explicitly required\n  for the change. The requirement to preserve initiating users through queued\n  work concerns actor attribution, not cross-version task compatibility.\n- In templates, use `{% translate %}` / `{% blocktranslate %}` for translatable\n  text.\n- Preserve accessibility and the existing Bootstrap/jQuery-based frontend\n  patterns. For user-facing HTML, CSS, or JavaScript changes, follow\n  `ACCESSIBILITY.md` and `docs/contributing/frontend.rst`, including keyboard\n  navigation, visible focus, semantic controls, labels/errors, and\n  non-color-only state.\n- Write commit messages using the Conventional Commits format\n  `<type>(<optional scope>): <description>`. Common types include `feat`,\n  `fix`, `docs`, `refactor`, `test`, `ci`, and `chore`. Example:\n  `fix(translations): handle empty component slug`. Include a concise commit\n  body describing the motivation. When the commit resolves an issue, add a\n  `Fixes #123` clause.\n- Pin dependencies to exact versions using `==`. Use a non-exact constraint\n  only when there is a deliberate reason, and document that reason next to the\n  dependency declaration, as is done for `certifi` to allow newer certificate\n  bundles.\n- Keep new project code under GPL-3.0-or-later and include the repository's\n  usual copyright and SPDX license header in new Python files.\n\n## Documentation expectations\n\n- Match the style of the surrounding page in `docs/`; prefer clear, direct,\n  instructional prose with short paragraphs over marketing language or large\n  rewrites.\n- Preserve the existing structure and heading hierarchy. Prefer extending an\n  existing section over creating a new one, and keep headings in sentence case\n  to match the current documentation.\n- Use Sphinx and reStructuredText conventions already present in the docs:\n  prefer semantic cross-references such as `:ref:`, `:doc:`, `:guilabel:`,\n  `:setting:`, `:wladmin:`, `:file:`, and `:program:` instead of raw links,\n  repeated explanations, or ad-hoc formatting.\n- Keep documentation changes scoped and additive when possible. Avoid\n  unnecessary rewrites or structure changes, especially because the\n  documentation is translated.\n- Document every new configuration option. Document native Django settings in\n  the appropriate settings documentation, typically `docs/admin/config.rst`,\n  and Docker-exposed environment variables in\n  `docs/admin/install/docker.rst`. Update both documentation surfaces when an\n  option is available through both mechanisms.\n- Use admonitions, screenshots, and code blocks only when they add concrete\n  value and match the style of the surrounding page.\n- Keep manually maintained explanations in the main documentation pages. In\n  `docs/snippets/`, do not hand-edit content inside autogenerated marker\n  blocks; manual explanatory text outside those blocks is preserved by the\n  generator and can be edited when appropriate.\n\n## Weblate-specific guardrails\n\n- Be careful with repository, webhook, and file-handling code; validate inputs\n  and avoid introducing path traversal, command injection, or script injection\n  risks.\n- Handle VCS operations defensively and surface failures cleanly.\n- Mock external VCS operations and API calls in tests.\n- Review `docs/security/threat-model.rst` when changing public endpoints,\n  authentication or token modes, deployment modes, backup or import formats, VCS\n  execution paths, outbound integration classes, add-on execution capabilities,\n  or security-relevant defaults for hooks, HTTPS, rate limits, CSP,\n  private-network access, or backup import limits.\n- Review does not necessarily require an edit. Update the threat model in the\n  same change only when its scope, actors, trust boundaries, assumptions,\n  claimed security properties, or triage dispositions change or leave a gap,\n  following its \"Conditions that change this model\" section. Features covered\n  by existing guidance do not need individual entries. Keep feature-level\n  endpoint, permission, configuration, implementation, and limit details in\n  the relevant feature or administration documentation; link to them only when\n  needed to explain a distinct boundary, exception, or triage outcome.\n- For user-visible changes, add or update a changelog entry in the top section\n  of `docs/changes.rst` for the upcoming release.\n- Do not alter changelog sections for already released versions; put follow-up\n  entries in the current unreleased section instead.\n- Keep changelog entries concise and link to the relevant documentation for the\n  feature instead of embedding long explanations in the changelog itself.\n- Minor fixes and fixes for features that have not been released yet do not\n  need a changelog entry.\n\n## GitHub discussions\n\n- GitHub organization discussion URLs such as\n  `https://github.com/orgs/WeblateOrg/discussions/19794` can still belong to the\n  `WeblateOrg/weblate` repository. When working with these URLs, resolve the\n  discussion through `WeblateOrg/weblate` repository discussions instead of\n  treating the URL as an issue, pull request, or organization-only object.\n- Use GitHub discussion-aware tooling, such as `gh api graphql` against\n  `repository(owner: \"WeblateOrg\", name: \"weblate\") { discussion(number: ...) }`,\n  when the regular GitHub issue or pull request connectors do not expose the\n  discussion.\n\n## Testing and linting instructions\n\n- Select test fixtures by their identifying fields or retain the object returned\n  when creating them. Do not use an unordered queryset's first row when the\n  assertion depends on which row was selected. Use an explicit `order_by()`\n  when order is the behavior under test.\n- Screenshot tests must explicitly configure the services and fixture data\n  visible in the captured UI. Do not depend on configuration inherited from\n  other tests or reusable database snapshots. Wait for asynchronous content to\n  finish loading before capture, and avoid competing providers whose response\n  order changes the rendered output.\n- Complex data migrations must have populated upgrade tests in `ci/run-migrate`:\n  add old-version setup and post-upgrade assertion scripts in\n  `ci/migrate-scripts/`, gated to applicable source releases. Seed data that\n  exercises conditional branches and cross-app relationships, and verify the\n  resulting data, not just successful migration execution. Empty-database runs\n  and helper tests against the latest schema do not detect missing migration\n  dependencies or premature access to future columns. Use historical models\n  from `apps.get_model()` and declare dependencies for the models accessed.\n  Keep migration database access independent of current model helpers.\n- For an isolated worktree environment, use the development container workflow\n  in `docs/contributing/start.rst` (`devcontainer` section). Run\n  `./scripts/devcontainer up`, then use `./scripts/devcontainer exec --` before\n  the commands below. Run `./scripts/devcontainer doctor` to diagnose setup,\n  and `./scripts/devcontainer bootstrap` after dependency changes. The test\n  environment uses PostgreSQL and Valkey; it does not start application workers.\n- Install the development dependencies first using\n  `uv sync --all-extras --dev`.\n- After syncing, prefer `uv run ...` for subsequent commands so they use the\n  virtual environment created in `.venv`. If needed, you can also activate it\n  with `source .venv/bin/activate` or invoke tools from `.venv/bin/`.\n- Prefer `uv run prek run --all-files` as the primary linting/formatting command because\n  it runs the repository's configured pre-commit framework checks.\n- `prek` is a third-party reimplementation of the `pre-commit` tool.\n- Prefer `prek` for Ruff checks and formatting; `uv run ruff ...` is not\n  guaranteed to work in this environment because Ruff can be provided only\n  through the pre-commit hook environment.\n- Use `pytest` to run the test suite: `uv run pytest`. On a fresh checkout,\n  first follow the local test setup in `docs/contributing/tests.rst`\n  (`DJANGO_SETTINGS_MODULE=weblate.settings_test`, `collectstatic`, and test\n  database prerequisites). `scripts/test-database.sh` can be sourced to set up\n  the database connection variables such as `CI_DB_USER`, `CI_DB_PASSWORD`,\n  `CI_DB_HOST`, and `CI_DB_PORT`. If tests cannot reach the configured\n  PostgreSQL server, do not assume it is stopped: local sandboxing can block\n  access to an already-running service. Retry with permission to access the\n  local service when sandboxing is the cause. Only when PostgreSQL is confirmed\n  not to be running, and it is installed as a local Linux service, try\n  `sudo service postgresql start` and rerun the failed command. Treat service\n  startup as a recovery step, not a prerequisite for every test invocation. If\n  you start PostgreSQL this way, stop it with `sudo service postgresql stop`\n  after the retry, whether the command succeeds or fails, so no service process\n  is left running when the task finishes.\n- Use `pylint` to lint the Python code: `uv run pylint weblate/ scripts/`\n- Use `mypy` to type check with the same command as CI:\n  `uv run mypy --show-column-numbers weblate scripts/*.py ./*.py | ./scripts/filter-mypy.sh`.\n- New or changed code should not introduce new mypy failures where current\n  Django typing support makes that practical. Existing non-enforced mypy\n  findings should not be worsened.\n","isInternal":false,"tokens":2852,"sizeBytes":13395}],"systemPromptSnippet":"<yakaai_skills repo=\"WeblateOrg/weblate\">\n<!-- File: AGENTS.md (Tokens: ~2852 | Category: root-instruction) -->\n# Agents guidance for Weblate\n\nThis file captures agent-specific guidance for working in the Weblate codebase.\nFor application-developer workflows and broader product integration guidance, use\n`docs/devel/` instead of repeating that material here.\n\n## Project overview\n\n- Weblate is a Django-based web translation platform with Celery background\n  tasks.\n- The primary stack is Python, Django, JavaScript, and HTML/CSS/Bootstrap.\n\n## Code expectations\n\n- Follow existing Django patterns and project conventions.\n- Prefer the repository's configured Ruff-based formatting and linting rules.\n- Use human-readable Ruff rule names in overrides, such as\n  `# ruff: ignore[assert]`; do not use or rewrite them to cryptic codes such as\n  `# noqa: S102`, `# ruff: N801`, or `# ruff: noqa: F841`.\n- Prefer type hints and use `from __future__ import annotations` in Python\n  modules.\n- Use `TYPE_CHECKING` imports for type-only dependencies when that avoids\n  runtime import cycles.\n- Add new user-configurable model fields to the existing REST serializers, API\n  documentation, schema, and API behavior tests for that model. Review write\n  permissions and validation explicitly. Keep secrets, computed state, and\n  intentionally internal fields unexposed, and document the reason when the\n  omission is not self-evident.\n- Keep user-data export, the ``weblate_schemas`` user-data schema, and account\n  settings import in sync. The export and schema should cover profile fields,\n  including fields intentionally excluded from import; omit internal database\n  identifiers and user relations. Validate uploads against the packaged schema\n  and model or form rules; import portable settings only, never counters, audit\n  history, credentials, or source account identifiers. Represent exported\n  project and component references with slugs or slug paths, never database IDs.\n- Do not add tests that duplicate OpenAPI schema expectations covered by the\n  tracked snapshot in `docs/specs/openapi.yaml`; schema changes are visible\n  during review. Allow focused tests of configuration-dependent behavior that\n  the snapshot cannot cover, and parsing and validation of served schema\n  documents without asserting fixed schema contents. Keep other tests focused\n  on API behavior, permissions, validation, schema endpoint availability, and\n  documentation UI integration.\n- All translatable user-facing strings must use Django i18n helpers. New\n  messages introduced exclusively for API responses must not be localized. API\n  responses may reuse localized messages generated by code shared with the UI,\n  including model, form, and validator errors. Do not disable localization,\n  replace shared messages with API-specific English messages, or require\n  separate UI/API messages solely to enforce nonlocalized API responses. Do not\n  flag reuse of shared localized messages as a review issue.\n- Messages written to persisted storage, such as the audit log, add-on log, or\n  changes, should not be localized.\n- Supply an explicit user when recording history changes. Automated operations\n  must use the appropriate system or add-on bot user rather than `None`.\n  Preserve the initiating user for settings changes and user-triggered creation,\n  including queued work and pending file writes. Keep the initiating actor\n  separate from the content author. Do not substitute a generic bot for a missing\n  actor.\n  Pass the anonymous user explicitly for intentional anonymous actions. Missing\n  history users currently trigger error reporting and a `RuntimeWarning`, which\n  pytest treats as an error. This is temporary soft enforcement in production,\n  not permission to omit the actor. Do not suppress the warning to hide missing\n  actors in tests; supply the correct user instead.\n- Weblate does not maintain compatibility for queued Celery task messages across\n  upgrades. Task signatures and payloads may change without legacy argument\n  adapters. Do not flag incompatibility with messages published by an older\n  release as a defect unless cross-version compatibility is explicitly required\n  for the change. The requirement to preserve initiating users through queued\n  work concerns actor attribution, not cross-version task compatibility.\n- In templates, use `{% translate %}` / `{% blocktranslate %}` for translatable\n  text.\n- Preserve accessibility and the existing Bootstrap/jQuery-based frontend\n  patterns. For user-facing HTML, CSS, or JavaScript changes, follow\n  `ACCESSIBILITY.md` and `docs/contributing/frontend.rst`, including keyboard\n  navigation, visible focus, semantic controls, labels/errors, and\n  non-color-only state.\n- Write commit messages using the Conventional Commits format\n  `<type>(<optional scope>): <description>`. Common types include `feat`,\n  `fix`, `docs`, `refactor`, `test`, `ci`, and `chore`. Example:\n  `fix(translations): handle empty component slug`. Include a concise commit\n  body describing the motivation. When the commit resolves an issue, add a\n  `Fixes #123` clause.\n- Pin dependencies to exact versions using `==`. Use a non-exact constraint\n  only when there is a deliberate reason, and document that reason next to the\n  dependency declaration, as is done for `certifi` to allow newer certificate\n  bundles.\n- Keep new project code under GPL-3.0-or-later and include the repository's\n  usual copyright and SPDX license header in new Python files.\n\n## Documentation expectations\n\n- Match the style of the surrounding page in `docs/`; prefer clear, direct,\n  instructional prose with short paragraphs over marketing language or large\n  rewrites.\n- Preserve the existing structure and heading hierarchy. Prefer extending an\n  existing section over creating a new one, and keep headings in sentence case\n  to match the current documentation.\n- Use Sphinx and reStructuredText conventions already present in the docs:\n  prefer semantic cross-references such as `:ref:`, `:doc:`, `:guilabel:`,\n  `:setting:`, `:wladmin:`, `:file:`, and `:program:` instead of raw links,\n  repeated explanations, or ad-hoc formatting.\n- Keep documentation changes scoped and additive when possible. Avoid\n  unnecessary rewrites or structure changes, especially because the\n  documentation is translated.\n- Document every new configuration option. Document native Django settings in\n  the appropriate settings documentation, typically `docs/admin/config.rst`,\n  and Docker-exposed environment variables in\n  `docs/admin/install/docker.rst`. Update both documentation surfaces when an\n  option is available through both mechanisms.\n- Use admonitions, screenshots, and code blocks only when they add concrete\n  value and match the style of the surrounding page.\n- Keep manually maintained explanations in the main documentation pages. In\n  `docs/snippets/`, do not hand-edit content inside autogenerated marker\n  blocks; manual explanatory text outside those blocks is preserved by the\n  generator and can be edited when appropriate.\n\n## Weblate-specific guardrails\n\n- Be careful with repository, webhook, and file-handling code; validate inputs\n  and avoid introducing path traversal, command injection, or script injection\n  risks.\n- Handle VCS operations defensively and surface failures cleanly.\n- Mock external VCS operations and API calls in tests.\n- Review `docs/security/threat-model.rst` when changing public endpoints,\n  authentication or token modes, deployment modes, backup or import formats, VCS\n  execution paths, outbound integration classes, add-on execution capabilities,\n  or security-relevant defaults for hooks, HTTPS, rate limits, CSP,\n  private-network access, or backup import limits.\n- Review does not necessarily require an edit. Update the threat model in the\n  same change only when its scope, actors, trust boundaries, assumptions,\n  claimed security properties, or triage dispositions change or leave a gap,\n  following its \"Conditions that change this model\" section. Features covered\n  by existing guidance do not need individual entries. Keep feature-level\n  endpoint, permission, configuration, implementation, and limit details in\n  the relevant feature or administration documentation; link to them only when\n  needed to explain a distinct boundary, exception, or triage outcome.\n- For user-visible changes, add or update a changelog entry in the top section\n  of `docs/changes.rst` for the upcoming release.\n- Do not alter changelog sections for already released versions; put follow-up\n  entries in the current unreleased section instead.\n- Keep changelog entries concise and link to the relevant documentation for the\n  feature instead of embedding long explanations in the changelog itself.\n- Minor fixes and fixes for features that have not been released yet do not\n  need a changelog entry.\n\n## GitHub discussions\n\n- GitHub organization discussion URLs such as\n  `https://github.com/orgs/WeblateOrg/discussions/19794` can still belong to the\n  `WeblateOrg/weblate` repository. When working with these URLs, resolve the\n  discussion through `WeblateOrg/weblate` repository discussions instead of\n  treating the URL as an issue, pull request, or organization-only object.\n- Use GitHub discussion-aware tooling, such as `gh api graphql` against\n  `repository(owner: \"WeblateOrg\", name: \"weblate\") { discussion(number: ...) }`,\n  when the regular GitHub issue or pull request connectors do not expose the\n  discussion.\n\n## Testing and linting instructions\n\n- Select test fixtures by their identifying fields or retain the object returned\n  when creating them. Do not use an unordered queryset's first row when the\n  assertion depends on which row was selected. Use an explicit `order_by()`\n  when order is the behavior under test.\n- Screenshot tests must explicitly configure the services and fixture data\n  visible in the captured UI. Do not depend on configuration inherited from\n  other tests or reusable database snapshots. Wait for asynchronous content to\n  finish loading before capture, and avoid competing providers whose response\n  order changes the rendered output.\n- Complex data migrations must have populated upgrade tests in `ci/run-migrate`:\n  add old-version setup and post-upgrade assertion scripts in\n  `ci/migrate-scripts/`, gated to applicable source releases. Seed data that\n  exercises conditional branches and cross-app relationships, and verify the\n  resulting data, not just successful migration execution. Empty-database runs\n  and helper tests against the latest schema do not detect missing migration\n  dependencies or premature access to future columns. Use historical models\n  from `apps.get_model()` and declare dependencies for the models accessed.\n  Keep migration database access independent of current model helpers.\n- For an isolated worktree environment, use the development container workflow\n  in `docs/contributing/start.rst` (`devcontainer` section). Run\n  `./scripts/devcontainer up`, then use `./scripts/devcontainer exec --` before\n  the commands below. Run `./scripts/devcontainer doctor` to diagnose setup,\n  and `./scripts/devcontainer bootstrap` after dependency changes. The test\n  environment uses PostgreSQL and Valkey; it does not start application workers.\n- Install the development dependencies first using\n  `uv sync --all-extras --dev`.\n- After syncing, prefer `uv run ...` for subsequent commands so they use the\n  virtual environment created in `.venv`. If needed, you can also activate it\n  with `source .venv/bin/activate` or invoke tools from `.venv/bin/`.\n- Prefer `uv run prek run --all-files` as the primary linting/formatting command because\n  it runs the repository's configured pre-commit framework checks.\n- `prek` is a third-party reimplementation of the `pre-commit` tool.\n- Prefer `prek` for Ruff checks and formatting; `uv run ruff ...` is not\n  guaranteed to work in this environment because Ruff can be provided only\n  through the pre-commit hook environment.\n- Use `pytest` to run the test suite: `uv run pytest`. On a fresh checkout,\n  first follow the local test setup in `docs/contributing/tests.rst`\n  (`DJANGO_SETTINGS_MODULE=weblate.settings_test`, `collectstatic`, and test\n  database prerequisites). `scripts/test-database.sh` can be sourced to set up\n  the database connection variables such as `CI_DB_USER`, `CI_DB_PASSWORD`,\n  `CI_DB_HOST`, and `CI_DB_PORT`. If tests cannot reach the configured\n  PostgreSQL server, do not assume it is stopped: local sandboxing can block\n  access to an already-running service. Retry with permission to access the\n  local service when sandboxing is the cause. Only when PostgreSQL is confirmed\n  not to be running, and it is installed as a local Linux service, try\n  `sudo service postgresql start` and rerun the failed command. Treat service\n  startup as a recovery step, not a prerequisite for every test invocation. If\n  you start PostgreSQL this way, stop it with `sudo service postgresql stop`\n  after the retry, whether the command succeeds or fails, so no service process\n  is left running when the task finishes.\n- Use `pylint` to lint the Python code: `uv run pylint weblate/ scripts/`\n- Use `mypy` to type check with the same command as CI:\n  `uv run mypy --show-column-numbers weblate scripts/*.py ./*.py | ./scripts/filter-mypy.sh`.\n- New or changed code should not introduce new mypy failures where current\n  Django typing support makes that practical. Existing non-enforced mypy\n  findings should not be worsened.\n</yakaai_skills>"}