Написання гарного патча

Записуйте окремі зміни

Це дратує, коли ви отримуєте великий патч, який, як кажуть, виправляє 11 дивних проблем, але обговорення і думки не збігаються з 10 з них або 9 з них вже були виправлені по-іншому. Тоді людині, яка зливає цю зміну, потрібно витягти єдиний цікавий патч звідкись із величезної купи джерел, і це створює багато додаткової роботи.

Бажано, щоб кожне виправлення, яке вирішує проблему, було окремим патчем/фіксом з власним описом/повідомленням про фіксацію, в якому точно вказується, що саме воно виправляє, щоб всі зміни могли бути вибірково застосовані супроводжувачем або іншими зацікавленими сторонами.

Крім того, окремі зміни дозволяють набагато краще розділити дані для відстеження проблем та регресій у майбутньому.

Документація

Документування може бути нудним завданням, але хтось повинен його виконувати. Буде набагато простіше, якщо ви надсилатимете документацію разом зі змінами коду. Будь ласка, не забувайте документувати методи, складні блоки коду або видимі користувачеві функції.

Дивись також

Посприяйте документуванню Weblate

Тестові випадки

Тести дозволяють нам швидко перевірити, чи працюють функції так, як вони повинні працювати. Щоб підтримувати цю ситуацію і покращувати її, всі нові можливості і функції, які додаються, повинні бути протестовані в тестовому наборі. Кожна функція, що додається, повинна отримати принаймні один правильний тестовий випадок, який підтверджує, що вона працює так, як задокументовано.

Дивись також

Комплекс тестування Weblate і неперервна інтеграція

Повідомлення щодо подання

Git-подання повинні відповідати специфікації Conventional Commits.

Перевірка типів

Any new code should utilize PEP 484 type hints. We are using mypy to check them because it has a Django plugin that makes type checking of Django apps practical.

New and changed code should not introduce new mypy failures where current Django typing support makes that practical. The code base is not yet completely covered by type annotations, and some Django constructs are difficult to annotate precisely. CI therefore enforces mypy only for selected modules and reports other findings separately.

Стандарт програмування та шліфування коду

Код має бути таким PEP 8 coding guidelines and should be formatted using 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 (принципів безпеки за компонуванням).

Керівні принципи ШІ

Вносячи контент до проекту, ви даєте нам дозвіл використовувати його як є, і ви повинні переконатися, що маєте право поширювати його нам. Надсилаючи нам зміни, ви погоджуєтеся з тим, що вони можуть і повинні бути прийняті проектом і поширюватися під ліцензією проекту. Автори повинні чітко усвідомлювати, що вони несуть відповідальність за те, щоб до проекту не потрапляв неліцензійний код.

Це не залежить від того, чи використовується штучний інтелект, чи ні.

Надсилаючи запит, ви, звісно, завжди повинні переконатися, що пропозиція є якісною і відповідає нашим рекомендаціям, а також докладено максимум зусиль. Основне емпіричне правило полягає в тому, що якщо хтось може помітити, що внесок був зроблений за допомогою штучного інтелекту, у вас є ще багато роботи.

Ми можемо прийняти до проєкту код, написаний за допомогою штучного інтелекту, але код все одно повинен відповідати стандартам кодування, бути написаним чітко, документованим, містити тестові випадки та дотримуватися всіх звичайних правил.