Contributing to LinuxCNC

The official LinuxCNC git repo is at https://github.com/linuxcnc/linuxcnc/

Anyone can get a read-only copy of the LinuxCNC source tree via git:

If you are a developer with push access, then follow github’s instructions for setting up a repository that you can push from.

Note that the clone command put the local LinuxCNC repo in a directory called linuxcnc-dev, instead of the default linuxcnc. This is because the LinuxCNC software by default expects configs and G-code programs in a directory called $HOME/linuxcnc, and having the git repo there too is confusing.

Issues and pull requests (abbreviated PRs) are welcome on GitHub: https://github.com/LinuxCNC/linuxcnc/issues https://github.com/LinuxCNC/linuxcnc/pulls

We use the "merging upwards" and "topic branches" git workflows described here:

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

У нас есть ветка разработки под названием «мастер» и одна или несколько стабильных веток с именами вроде «2.6» и «2.7», указывающими номер версии выпусков, которые мы делаем из нее.

Исправления идут в самой старой применимой стабильной ветке, и эта ветка объединяется со следующей, более новой стабильной веткой, и так далее до «мастера». Коммиттер исправления может сделать слияние самостоятельно или оставить слияние для кого-то другого.

Новые функции обычно помещаются в ветку master, но некоторые виды функций (в частности, хорошо изолированные драйверы устройств и документация) могут (по усмотрению менеджеров выпуска стабильной ветки) помещаться в стабильную ветку и объединяться, как это делается с исправлением ошибок.

В Интернете есть много отличных бесплатных руководств по git.

Первое место, куда стоит заглянуть, это, вероятно, man-страница 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).

Используйте первую строку как краткое изложение цели изменения (почти как строку темы электронного письма). За ним следует пустая строка, а затем более длинное сообщение, объясняющее изменение. Пример:

Исправления должны идти в самой старой применимой ветке. Новые функции должны идти в основной ветке. Если вы не уверены, куда относится изменение, спросите в irc или в списке рассылки.

Когда это уместно, организуйте свои изменения в ветку (серию коммитов), где каждый коммит является логическим шагом к вашей конечной цели. Например, сначала вынесите какой-нибудь сложный код в новую функцию. Затем, во втором коммите, исправьте базовую ошибку. Затем в третьем коммите добавьте новую функцию, которая упрощается благодаря рефакторингу и которая не работала бы без исправления этой ошибки.

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

Постарайтесь следовать преобладающему стилю отступов окружающего кода. В частности, изменения пробелов затрудняют другим разработчикам отслеживание изменений с течением времени. Когда необходимо выполнить переформатирование кода, делайте это как коммит отдельно от каких-либо семантических изменений.

Тест «retval < 0» должен показаться вам знакомым; это тот же тест, который вы используете в пользовательском пространстве (возвращает -1 в случае ошибки) и в пространстве ядра (возвращает -ERRNO в случае ошибки).

С git можно записывать каждое редактирование и фальстарт как отдельный коммит. Это очень удобно как способ создания контрольных точек во время разработки, но часто вы не хотите делиться этими фальстартами с другими.

Git предоставляет два основных способа очистки истории, оба из которых можно использовать свободно, прежде чем делиться изменениями:

git commit --amend позволяет вам внести дополнительные изменения в последнюю вещь, которую вы закоммитили, а также при необходимости изменить сообщение коммита. Используйте это, если вы сразу поняли, что что-то упустили из коммита, или если вы опечатались в сообщении коммита.

git rebase --interactive upstream-branch позволяет вернуться к каждому коммиту, сделанному с тех пор, как вы разветвили свою ветку функций из восходящей ветки, возможно, отредактировав коммиты, отбросив коммиты или смешав (объединив) коммиты с другими. 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, включая выполнение регрессионных тестов):

Это либо сообщит All is well, либо Broke on <commit>

Пожалуйста, используйте возможность переименования файлов очень осторожно. Подобно применению отступов для отдельных файлов, переименования по-прежнему затрудняют отслеживание изменений с течением времени. Как минимум, вы должны искать консенсус в irc или списке рассылки, что переименование является улучшением.

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