Внесок у LinuxCNC

Офіційний git-репозиторій LinuxCNC знаходиться за адресою https://github.com/linuxcnc/linuxcnc/

Будь-хто може отримати копію вихідного коду LinuxCNC лише для читання через git:

Якщо ви розробник із доступом до push-розсилок, дотримуйтесь інструкцій github щодо налаштування репозиторію, з якого ви можете надсилати дані.

Зверніть увагу, що команда clone розміщує локальне сховище LinuxCNC у каталозі з назвою linuxcnc-dev, а не у стандартному каталозі linuxcnc. Це пов’язано з тим, що програмне забезпечення LinuxCNC за замовчуванням очікує, що конфігурації та програми G-коду будуть розміщені у каталозі з назвою $HOME/linuxcnc, і наявність там також сховища git може викликати плутанину.

Проблеми та запити на впровадження (скорочені PR) вітаються на GitHub: . https://github.com/LinuxCNC/linuxcnc/issues . https://github.com/LinuxCNC/linuxcnc/pulls

Ми використовуємо робочі процеси git "злиття вгору" та "тематичні гілки", описані тут:

https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html

У нас є гілка розробки під назвою master, та одна або декілька стабільних гілок з назвами типу 2.6 та 2.7, що вказують на номер версії релізів, які ми з неї створюємо.

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

Нові функції зазвичай додаються до гілки «master», але деякі типи функцій (зокрема, добре ізольовані драйвери пристроїв та документація) можуть (на розсуд менеджерів стабільної гілки) додаватися до стабільної гілки та об’єднуватися так само, як і виправлення помилок.

В інтернеті є багато чудових безкоштовних навчальних посібників з git.

Перше місце, куди варто звернутися, — це, мабуть, сторінка довідки «gittutorial». Цю сторінку довідки можна відкрити, виконавши команду «man gittutorial» у терміналі (якщо у вас встановлені сторінки довідки git). Gittutorial та супутня документація також доступні в Інтернеті за адресою:

Для більш детальної документації git дивіться книгу "Pro Git": https://git-scm.com/book

Ще один рекомендований онлайн-посібник – «Git для ледачих»: https://wiki.spheredev.org/index.php/Git_for_the_lazy

Зробіть ваші коміти невеликими та лаконічними. Кожен коміт має виконувати одну логічну зміну в репозиторії.

Тримайте повідомлення комітів завширшки приблизно 72 стовпці (щоб у вікні терміналу розміру за замовчуванням вони не переносилися при відображенні git log).

Використовуйте перший рядок як короткий виклад наміру зміни (майже як тему електронного листа). Після нього додайте порожній рядок, а потім довше повідомлення з поясненням зміни. Приклад:

Виправлення помилок слід розміщувати в найстарішій відповідній гілці. Нові функції слід розміщувати в гілці master. Якщо ви не впевнені, де знаходиться зміна, запитайте в irc або у списку розсилки.

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

Це корисно для рецензентів, оскільки легше побачити, що крок «винести код у нову функцію» був правильним, коли немає інших редагувань; легше побачити, що помилка виправлена, коли зміна, яка її виправляє, відокремлена від нової функції; і так далі.

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

Тест "retval < 0" має бути знайомим; це такий самий тип тесту, який використовується в просторі користувача (повертає -1 у разі помилки) та в просторі ядра (повертає -ERRNO у разі помилки).

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

Git пропонує два основні способи очищення історії, обидва з яких можна зробити безкоштовно, перш ніж поділитися змінами:

git commit --amend дозволяє внести додаткові зміни до останнього коміту, а також, за бажанням, змінити повідомлення про коміт. Використовуйте цю команду, якщо ви відразу зрозуміли, що щось пропустили в коміті, або якщо ви зробили помилку в повідомленні про коміт.

git rebase --interactive upstream-branch дозволяє повернутися до кожного коміту, зробленого з моменту відгалуження вашої гілки функцій від гілки upstream, з можливістю редагування комітів, видалення комітів або об’єднання (squashing) комітів з іншими. Rebase також можна використовувати для розділення окремих комітів на кілька нових комітів.

Якщо ваші зміни складаються з декількох патчів, можна використати git rebase -i, щоб перевпорядкувати ці патчі в послідовність комітів, яка чіткіше відображає етапи вашої роботи. Потенційним наслідком перевпорядкування патчів може бути неправильне визначення залежностей — наприклад, введення змінної, а оголошення цієї змінної з’являється лише в наступному патчі.

Хоча гілка HEAD буде компілюватися, не кожна коміт може компілюватися в такому випадку. Це порушує роботу git bisect — інструменту, який хтось інший може використовувати пізніше для пошуку коміту, що спричинив появу помилки. Тому, крім того, що ви повинні переконатися, що ваша гілка компілюється, важливо також переконатися, що кожна окрема коміт також компілюється.

Існує автоматичний спосіб перевірки гілки на можливість побудови кожного коміту — див. https://dustin.sallings.org/2010/03/28/git-test-sequence.html та код за адресою https://github.com/dustin/bindir/blob/master/git-test-sequence. Використовуйте наступним чином (у цьому випадку тестується кожна коміт від origin/master до HEAD, включаючи виконання регресійних тестів):

Це або повідомить «Все гаразд», або «Зламано <commit>»

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

Використовуйте git pull --rebase замість простої git pull для збереження гарної лінійної історії. Коли ви переосновуєте свою роботу, ви завжди зберігаєте її як ревізії, які пропереду origin/master, тому можете робити такі речі, як git-patch їх поділитися з іншими без натиску до центрального сховища.