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

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

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

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

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

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

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

Дивись також

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

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

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

Дивись також

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

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

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

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

Будь-який новий код повинен використовувати підказки типів PEP 484. Ми використовуємо mypy для перевірки (оскільки він має плагін Django, який дозволяє перевіряти типи в застосунках Django).

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

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

Код має бути таким PEP 8 coding guidelines and should be formatted using ruff форматувальник коду.

Для перевірки якості коду ви можете скористатися ruff — її налаштування зберігаються у pyproject.toml.

Найпростішим підходом для запровадження примусового виконання усіх умов є встановлення сховища pre-commit. Weblate, у якому містяться налаштування для перевірки внесених файлів на відповідність умовам. Після встановлення сховища (його вже включено у pyproject.toml) увімкніть його за допомогою команди pre-commit install у клоні сховища Weblate. У такий спосіб ви зможете автоматично перевіряти усі внесені вами зміни.

Ви також можете запустити перевірку вручну. Щоб перевірити усі файли:

pre-commit run --all

Безпечне кодування

Будь-який код для Weblate має бути написано із використанням Security by Design Principles (принципів безпеки за компонуванням).

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

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

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

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

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