{"owner":"WeblateOrg","repo":"weblate","hasSkills":true,"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 tests for that model. Review write permissions and\n  validation explicitly. Keep secrets, computed state, and intentionally\n  internal fields unexposed, and document the reason when the omission is not\n  self-evident.\n- All user-facing strings must be translatable using Django i18n helpers, except\n  messages used in the API or persisted storage, such as the audit log, add-on\n  log, or changes; these messages should not be localized.\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`.\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- 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- Check `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- Update `docs/security/threat-model.rst` in the same change when the threat\n  model's \"Conditions that change this model\" apply, including when unsupported\n  components become supported product surface, claimed security properties\n  change, or a vulnerability report exposes a model gap.\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- 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`.\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 tests for that model. Review write permissions and\n  validation explicitly. Keep secrets, computed state, and intentionally\n  internal fields unexposed, and document the reason when the omission is not\n  self-evident.\n- All user-facing strings must be translatable using Django i18n helpers, except\n  messages used in the API or persisted storage, such as the audit log, add-on\n  log, or changes; these messages should not be localized.\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`.\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- 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- Check `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- Update `docs/security/threat-model.rst` in the same change when the threat\n  model's \"Conditions that change this model\" apply, including when unsupported\n  components become supported product surface, claimed security properties\n  change, or a vulnerability report exposes a model gap.\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- 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`.\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","title":"AGENTS.md","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 tests for that model. Review write permissions and\n  validation explicitly. Keep secrets, computed state, and intentionally\n  internal fields unexposed, and document the reason when the omission is not\n  self-evident.\n- All user-facing strings must be translatable using Django i18n helpers, except\n  messages used in the API or persisted storage, such as the audit log, add-on\n  log, or changes; these messages should not be localized.\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`.\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- 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- Check `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- Update `docs/security/threat-model.rst` in the same change when the threat\n  model's \"Conditions that change this model\" apply, including when unsupported\n  components become supported product surface, claimed security properties\n  change, or a vulnerability report exposes a model gap.\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- 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`.\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","category":"root","tokens":1807}]}