Зміни в коді¶
Ця сторінка допоможе Вам поєднати свої зміни з Ubuntu Touch. Ми описуємо необхідні речі, які ми шукаємо в коді, виправленнях та змінах. Також ми дивимося на те, що можна очікувати від процесу перегляду коду.
Застереження¶
Ця сторінка не містить інформації про те як створювати програми або удосконалювати Ubuntu Touch. Інформацію про те як розробляти компоненти Ubuntu Touch можна знайти у розділі System software development. Про розробку програм написано у розділах Розробка програм та Попередньо встановлені програми.
Ця сторінка передбачає, що Ви знаєте, як записати свої зміни, як використовувати Git для їх долучення, як в разі необхідності пушити їх до Github або Gitlab, відгалужувати (форк) репозиторій та як подавати запит на злиття (PR) до GitHub або запит на злиття (MR) до GitLab.
Визначення¶
Оскільки ми використовуємо GitHub або GitLab для нашого хостингу коду залежно від компонента, деякі терміни в цьому документі ми використовуємо взаємозамінно.
- набір змін
Запит на злиття на GitHub (Pull Request, PR) або на GitLab (Merge Request, MR).
- звіт про помилку
Проблема (Issue) на GitHub або на GitLab.
Пояснення¶
Різні користувачі користуються Ubuntu Touch на багатьох різних пристроях. Порушити функціональність, на яку покладаються ці користувачі, може бути катастрофічним. Наш процес перегляду допомагає нам уникнути збоїв у функціональності, забезпечуючи деякі властивості набору змін.
Особливо, ми хочемо переконатися, що зміни:
відповідають власним цілям, таким як додавання функцій або виправлення помилок
не стануть причиною якоїсь неочікуваної поведінки
допоможуть комусь у майбутньому робити зміни в програмі в зручний спосіб
Правила на цій сторінці пояснюють, як потрібно писати та оформлювати свої зміни до Ubuntu Touch. Дотримання цих правил спрощує процес перевірки для Вас і для нас.
Ці правила не є абсолютними і ми не будемо автоматично відхиляти Вашу пропозицію змін на основі того, чи дотримуєтесь Ви правил. Якщо не дотримуєтеся, то переконайтеся, що зможете пояснити, чому.
Контрольний список для змін у коді¶
Пам’ятайте про контрольний список під час написання свого коду та підготовки до надсилання своїх змін.
Не надсилайте код з коментарями¶
Як усі розробники, ми часто залишаємо у своєму коді коментарі, які допомагають розуміти код (напр., вивід у консолі повідомлень журналу). Переконайтеся, що Ви не залишили жодних коментарів у своїх запитах на зміни (комітах). Якщо відчуваєте, що є стійка необхідність відступити від правила, переконайтеся, що є пояснення чому цей коментар залишений в коді. Наприклад, можна використати такі додаткові коментарі: // TODO: чи // FIXME:, залежно від того чи це звіт про помилку в самому коді чи це порада що саме ЗРОБИТИ в коді.
Напишіть тести до своїх змін¶
Якщо компонент має тестовий набір, використовуйте його. Переконайтесь, що Ви знаєте, як запустити тести для компонента та розумієте результати цих тестів. Ця інформація повинна міститися у файлі README компонента. Якщо цього немає та Ви не знаєте, як це знайти, запитайте у нас. Ми раді допомогти, коли хтось намагається розібратися з компонентом вперше. Однак будьте готові отримати у відповідь купу посилань на документацію на системи збірки або тестовий фреймворк, а не список команд для запуску. Це може бути все, що ми можемо надати у вільний час. Якщо у Вас після ознайомлення з отриманими матеріалами залишаються сумніви, не соромтеся запитати про свої конкретні проблеми ще раз. Ми були б дійсно Вам вдячні, якби Ви додали свої нові знання до README компонента. Найкращий час для написання документації — це одразу після чогось зробленого вперше.
Як тільки розберетеся як запустити тестовий набір, можете додати свої тести. Переконайтеся, що Ви перевіряєте якомога більше аспектів своєї нової функціональності, на скільки вважаєте це необхідним. Подивіться ще раз збоку на тести: ми рідко просимо видаляти тести, але можемо попросити щось додати.
Якщо Ви помітили, що компонент не має тестового набору, це чудовий час повідомити про помилку у цьому компоненті! Ми будемо вдячні за Вашу допомогу з додаванням тестового набору, але це не те що ми можемо вимагати.
Дотримуйтеся будь-яких наявних посібників стилю¶
Якщо репозиторій має посібник або рекомендації щодо стилю, користуйтеся ним. Якщо його немає, спробуйте дотримуватися наявного стилю, який є у файлі де Ви вносите зміни.
Контрольний список для реєстрації змін (commit)¶
Через якийсь час після написання коду нам часто потрібно розуміти, як і чому він призводить до помилки. Повідомлення до змін — це наш перший крок у розумінні цих складних питань. Цей контрольний список допомагає майбутнім зацікавленим у Вашому коді зрозуміти, чому це зроблено в такий спосіб.
Як приклад серії комітів (commit), які дуже добре відповідають цим головним принципам, подивіться на три коміти зверху журналу git log leading to 840777f з Lomiri. Не кожна зміна вимагає такого поглибленого опису, як ці приклади. Подивіться збоку на деталі; іноді Ви той самий, хто озирається на свої коміти і цікавиться, чому те чи інше було зроблене.
Дайте відповіді на чіткі запитання до повідомлень комітів¶
Ми відповідаємо на такі запитання як «що?» «чому?» та «як?», оскільки вони допомагають швидко зрозуміти контекст ситуації.
Намагайтеся відповісти на ці запитання у своїх метаданих до комітів або у самому вмісті. Це допоможе рецензентам та майбутнім читачам зрозуміти контекст змін. У порядку важливості, надайте відповіді:
- Що?
Дайте відповідь на це запитання у перших рядках коментаря до коміту. «Що робить Ваш коміт?» «Оптимізує шпалери для часу завантаження та використання пам’яті».
- Чому?
Завжди вказуйте підставу внесення змін: виправлені помилки, нові функції, та особливо обмеження, через які вони виглядають складнішими, ніж очікується. Надайте постійні посилання на звіт щодо проблеми або на документацію, якщо вони містять відповідний контекст.
- Хто?
Git вставляє Ваші ім’я та адресу е-пошти як автора змін. Якщо хтось інший допоміг Вам написати ці зміни, потрібно у Вашому коментарі до коміту додати співавтора за допомогою рядка
Co-Authored-By: Ім'я <email@example.com>.
Частину цього контексту можна надати в коментарях до коду, а не до коміту. Коментарі можуть допомогти людям, які лише читають код без використання таких інструментів, як git blame. Пам’ятайте, що коментарі можуть застаріти швидше за код, до якого вони написані. Коментарі до коміту пов’язані лише з кодом, який Ви написали.
На завершення переконайтеся, що Ви подумали про запитання, які можуть виникнути у Вас чи у когось іншого щодо Вашого коду в майбутньому і надали на них відповіді.
Робіть коміти якомога меншими, але не менше¶
Деякі зміни потребують виконання кількох логічних кроків. Якщо це так, розділіть ці кроки на окремі коміти. Кожен коміт має відповідати всьому контрольному списку. Він не повинен вимагати будь-яких майбутніх комітів для збірки або проходження тестів.
Скажімо, Ви додаєте новий спосіб пошуку телефонних номерів у програмі для дзвінків. Ваше виправлення вимагає трьох окремих кроків:
Виправлення помилки чи помилок у поточному пошуку телефонних номерів
Додавання нового API для підтримки Вашого нового пошуку
Додавання елементів інтерфейсу для Вашого нового пошуку
Якщо Ви виконаєте усі ці зміни одним комітом, а в третьому кроці, наприклад, буде помилка, ми скасуємо весь набір змін. Якщо зміни розділити на декілька комітів, виправлення помилки та новий API можуть бути додані до основного репозиторію доки Ви продовжите працювати над інтерфейсом.
Якщо можливо, змініть базу змін (rebase) під час перевірки¶
Зазвичай журнал комітів на GitHub виглядає приблизно так:
Виправлення помилки пошуку телефонного номера
Додавання нового виклику API для нового пошуку телефонних номерів
Додавання інтерфейсу для нового пошуку телефонних номерів
Виправлення інтерфейсу
Виправлення попереднього виправлення
Перегляд змін
Виправлення API після коментарів від рецензентів
Якщо Вам буде потрібно повернутися до цього журналу змін, Ви можете швидко заплутатися. Що сказали рецензенти, що не так з користувацьким інтерфейсом та з виправленням помилок?
Не додавайте новий коміт, коли Ви отримуєте виправлення, яке впливає на перший коміт з Вашого набору. Натомість змініть перший коміт. Якщо це змінить опис у Вашому повідомленні до коміту, оновіть його також.
Для редагування комітів потрібно вивчити нові інструменти Git. Змінюйте послідовності комітів з git-rebase. Надсилайте результативні зміни з примусовим push або створюйте нові гілки branch та відкривайте нові набори змін changeset.
На щастя, існують графічні інструменти для виконання цієї роботи більш вправно. Але на жаль, якщо Ви не маєте розуміння що вони роблять з командним рядком Git, це може Вас збентежити і Вам доведеться починати спочатку зі старих серій. Навіть досвідчені професіонали Git інколи розгублюються, тож не хвилюйтеся. Майже завжди є можливість повернутися до попереднього кроку.
Кожен коміт повинен після Ваших змін збиратися, запускатися та успішно проходити тести.
Відформатуйте правильно коментар до коміту¶
Збережіть перший рядок коментаря до свого коміту (так званий підсумок) до 50 або менше знаків. Кожен інший рядок у коментарі повинен мати 72 або менше знаків. Це нормально, якщо Вам іноді потрібно порушити правила — деякі зміни неможливо підсумувати у 50 символів, а деякі посилання довше за 72.
Контрольний список опису набору змін¶
Переконайтеся, що Ваш набір змін відповідає на такі запитання з таким описом.
Якщо Ви дотримувалися настанов щодо повідомлень до комітів, то, ймовірно, зможете скопіювати відповідну інформацію з них до свого опису набору змін. GitHub та GitLab зроблять це за Вас однією дією. Опис, у якому написано: «складно пояснити, будь ласка, прочитайте повідомлення про коміти», також прийнятний. Ми віримо, що Ви втримаєте баланс.
Яку проблему вирішує Ваш набір змін?¶
Прив’яжіть набори змін (чейнджсети) до звітів про помилки, які цими наборами виправляються, незалежно від того, чи Ви додаєте нову функцію, чи саме розв’язуєте проблему. Зазначте пристрої, на яких виникає проблема, чи стосується вона усіх пристроїв. Надайте достатньо інформації, щоб хтось міг згодом переглянути її та зрозуміти, як можна відтворити проблему чи протестувати функцію. Також додайте цю інформацію до звіту про проблему, якщо її там немає.
Наприклад:
Як Ви переконалися, що зміна була успішною?¶
Усі зміни вимагають перевірок, чи дійсно вони виправляють описане у звіті про помилку. Перелік оточення, в якому виконувалося тестування, включно з операційною системою, її версією та пристрої на яких проходив тест. Опишіть свій процес тестування. Якщо Ви не впевнені як перевірити функцію, пов’язану зі змінами, згадайте про це.
Наприклад:
Я перевірив цю зміну у програмі для здійснення дзвінків на Nexus 5. Вона має працювати на всіх пристроях, оскільки не змінює нічого, що стосується певної моделі, але наперед дякую за додаткові тести. Для виправлення помилки, мені довелося торкнутися фрагмента коду в області пошуку номера телефону (#53). Я не до кінця розумію, як перевірити це на регресії.
Чи потрібно вбудовувати (merge) будь-які зміни до, чи після цього набору змін?¶
Деякі зміни залежать від однієї або декількох змін перед тим як усе працюватиме правильно. Якщо це такий випадок, Вам слід задокументувати ці залежності в описі до свого набору змін. Якщо це потрібно, опишіть усі набори, які потрібно долучити до та після поточного у послідовності.
До прикладу, скажімо, Ви направили три запити на злиття на GitLab, ubports/core/docs!1, ubports/core/code!2 та ubports/core/infrastructure!3. Вони повинні бути опрацьовані у такому порядку. В такому випадку описи Ваших запитів на злиття (MR) повинні були б містити щось таке:
У
ubports/core/docs!1:ubports/core/code!2 та ubports/core/infrastructure!3 залежать від цього MR.
У
ubports/core/code!2:ubports/docs!1 повинні бути долучені перед цим запитом (MR). ubports/core/infrastructure!3 залежить від цього MR.
У
ubports/core/infrastructure!3:ubports/docs!1 та ubports/core/infrastructure!3 потрібно долучити до цього MR.
Як виглядає інтерфейс до та після цієї зміни?¶
Якщо Ваші зміни змінюють вигляд інтерфейсу, додайте знімки екрана для ілюстрації цих змін.
Подання та розгляд¶
Тепер, коли Ви перевірили свій набір змін, настав час для надсилання його на перегляд! Дякуємо Вам наперед за участь в Ubuntu Touch. Ось чого Ви можете очікувати від нас, коли ми переглянемо Ваші зміни.
Ми Вас поважаємо¶
Ви обрали використати свій час для допомоги Ubuntu Touch. Таке рішення ніколи не буває легким. Рецензент повинен ставитися до Вас із повагою та співпрацювати з Вами, щоб довести Ваш набір змін до того, коли він стане частиною Ubuntu Touch.
Повага — це дорога з двома напрямами. Ubuntu Touch — великий проєкт і рук для виконання усієї потрібної роботи завжди замало. Час для приділення уваги Вашому набору змін може затягнутися, та після довгого очікування, Ви можете повернутися та побачити суворий запит на зміни. Сприймайте таке «суворе» повідомлення, не як образу, а як намір працювати найшвидше. Таку ж благодать ми розширюємо і на Вас.
Ми ставимо багато запитань¶
Рецензенти краще зрозуміють код, який Ви змінюєте, після запитань про те як це працює. Вони можуть розуміти, що робить Ваш код, але вони запитають знову. Якщо Ви можете пояснити як працює Ваш код, найімовірніше Ви виконали правильне тестування.
Якщо Ви не можете пояснити роботу чогось, це червоний прапор. Ймовірно, ця зміна обходить іншу помилку, яка може знову переслідувати нас у майбутньому. Виправлення справжньої помилки замість пошуку обхідних шляхів – це найкраще використання часу.
Ми просимо про зміни¶
Хтось інший може побачити у Вашому коді проблеми, які Ви не помітили. Незалежно від того, чи ці проблеми є неефективністю, помилками стилю чи новими багами, їх, швидше за все, виявлять Ваші рецензенти, а не Ви. Не хвилюйтеся, якщо Ви отримаєте від рецензента том запитів на зміни. Ніхто не ідеальний. Пошук та усунення цих потенційних проблем призводить до швидшої та стабільнішої роботи Ubuntu Touch. Це не є зневагою до Ваших навичок розробника.
Ми можемо просити про значні зміни¶
Іноді рецензенти можуть побачити у зміні значно глибшу проблему компонента. Іноді Ви можете розпочати розробку з помилкового припущення та завершити її навалою коду спагеті. Так чи інакше, це хибний шлях до мети. Що б там не було причиною, Ваш рецензент вказує на можливі проблеми, пов’язані з Вашими змінами, та конструктивно пропонує новий напрямок руху.
Ви можете сказати нам, що ми помиляємося¶
Ви можете бути певними, що основну помилку нелегко виправити або що обраний Вами шлях є найкращим. Вам може бракувати часу на точне виправлення, як запитано. Якщо Ви думаєте, з будь-якої причини, що відкидання Вашого набору змін помилкове, сповістіть нам. Рецензенти спробують знайти з Вами спільне рішення у найкращий для наших користувачів спосіб.
Злиття та обслуговування¶
Після отримання переконання, що Ваш набір змін відповідає усім вимогам, він стає частиною Ubuntu Touch. Дякуємо Вам! Ви є частиною невеликої групи людей, які належать до чудової спільноти. Хоча це не кінець роботи.
Буває так, що Ваші зміни порушують роботу якихось функцій Ubuntu Touch, всупереч усім нашим зусиллям. Якщо це станеться Вас можуть попросити допомогти у дослідженні джерела проблеми та підготувати виправлення. Вашу зміну можуть скасувати, якщо ми виявимо, що вона була прямою причиною помилки, і ми не зможемо з Вами зв’язатися.
Нові співавтори можуть помітити, що Ви нещодавно працювали над елементом, над яким хочуть працювати вони. Ми були б Вам вдячні, якби Ви допомогли їм навчитися тому, що Ви вже про це знаєте.
Якщо немає нічого іншого, залишайтеся поруч із тими, хто дякує Вам за зроблені Вами зміни. Спільнота Ubuntu Touch підтримує один одного та неймовірно вдячна. Вам було б прикро пропустити свою частку гарного настрою.