Исходный код Weblate¶
Weblate разрабатывается на GitHub’е. Вы можете создавать форки и открывать запросы на извлечение. Патчи в любой другой форме также приветствуются.
См. также
Чтобы понять, как Weblate устроен изнутри, посмотрите раздел Внутреннее устройство Weblate.
Лицензия и авторское право¶
При внесении кода проекта вы соглашаетесь разместить свои изменения и новый код под лицензией репозитория, GPL-3.0-or-later, если не указано иное и не согласовано иначе. Новые исходные файлы должны соответствовать существующему стилю заголовков лицензий с указанием авторских прав и SPDX.
Используйте другую лицензию только при наличии обоснованной причины, например, для файлов, общих с репозиториями, использующими более разрешительные лицензии.
См. также
Лицензия Weblate объясняет лицензирование более подробно.
Написание хорошего патча¶
Создавайте отдельные изменения¶
Раздражает, когда вы получаете массивный патч, который, как говорят, исправляет 11 разных проблем, но обсуждения и мнения не согласуются с 10 из них, или 9 из них уже были исправлены иначе. Тогда человеку, объединяющему это изменение, нужно извлечь единственный интересный патч откуда-то из огромной кучи исходных кодов, и это создаёт много лишней работы.
Желательно, чтобы каждое исправление, устраняющее проблему, было в своём собственном патче/коммите со своим собственным описанием/сообщением коммита, в котором точно указано, что они исправляют, чтобы все изменения могли быть выборочно применены мейнтейнером или другими заинтересованными сторонами.
Кроме того, раздельные изменения позволяют гораздо лучше использовать биссекцию для отслеживания проблем и регрессов в будущем.
Документация¶
Документация может быть утомительной задачей; тем не менее, кому-то необходимо её завершить. Это значительно упрощает задачу, если вы отправляете документацию вместе с изменениями кода. Пожалуйста, не забывайте документировать методы, сложные блоки кода или видимые пользователю функции.
См. также
Тестовые случаи¶
Тесты позволяют нам быстро убедиться, что функции работают так, как должны. Чтобы поддерживать и улучшать эту ситуацию, все новые функции, которые добавляются, должны быть протестированы в наборе тестов. Каждая добавляемая функция должна иметь по крайней мере один действительный тестовый пример, который подтверждает, что она работает так, как задокументировано.
Сообщения коммита¶
Коммиты Git должны следовать спецификации Conventional Commits.
Проверка типов¶
Любой новый код должен использовать подсказки типов PEP 484. Мы используем mypy для их проверки, поскольку у него есть плагин Django, который делает проверку типов приложений Django практичной.
Новый и изменённый код не должен создавать новые сбои mypy там, где текущая поддержка типов Django делает это практичным. База кода ещё не полностью покрыта аннотациями типов, а некоторые конструкции Django сложно точно аннотировать. Поэтому CI применяет mypy только для выбранных модулей и сообщает о других результатах отдельно.
Стандарт и стиль программирования¶
Код должен следовать рекомендациям по оформлению кода PEP 8 и должен быть отформатирован с помощью форматтера кода ruff.
Для проверки качества кода можно использовать ruff, её конфигурация хранится в pyproject.toml.
Самый простой способ обеспечить всё это — установить prek. Это сторонняя реализация инструмента pre-commit, используемого Weblate. Он включён в зависимости разработки, объявленные в pyproject.toml, поэтому установка этих зависимостей делает prek доступным.
Чтобы проверить все файлы вручную, выполните:
uv run prek run --all-files
Если вы предпочитаете оригинальный клиент pre-commit, он использует ту же конфигурацию из .pre-commit-config.yaml.
Безопасное программирование¶
Любой код для Weblate должен быть написан с учётом Security by Design Principles (принципов безопасности по проектированию).
Рекомендации по ИИ¶
При внесении контента в проект вы даёте нам разрешение использовать его как есть, и вы должны убедиться, что имеете право распространять его нам. Отправляя нам изменение, вы соглашаетесь, что изменения могут и должны быть приняты проектом и перераспределены под лицензией проекта. Авторы должны явно осознавать, что на них лежит ответственность за то, чтобы в проект не был отправлен нелицензионный код.
Это не зависит от того, используется ИИ или нет.
При отправке запроса на извлечение вы, конечно, всегда должны убедиться, что предложение имеет хорошее качество и является наилучшим возможным в рамках наших рекомендаций. Основное эмпирическое правило: если кто-то может заметить, что вклад был сделан с помощью ИИ, вам предстоит ещё поработать.
Мы можем принять код, написанный с помощью ИИ, в проект, но код по-прежнему должен соответствовать стандартам кодирования, быть написан чётко, документирован, содержать тестовые примеры и соответствовать всем обычным требованиям, которые у нас есть.