Контроль версий для оборудования с открытым исходным кодом: 10 шагов

2024 Автор: John Day | [email protected]. Последнее изменение: 2024-01-30 11:52

У команды Brainbow есть несколько проектов в области электроники, и мы хотели поделиться своим процессом использования контроля версий для управления рабочим процессом проектирования электроники. Этот рабочий процесс использовался для больших и малых проектов, от простых двухслойных плат до сложных 10-слойных гигантов, и основан на инструментах с открытым исходным кодом. Надеюсь, другие смогут адаптировать наш рабочий процесс для себя и получить преимущества контроля версий для своих собственных проектов. Но какие преимущества контроль версий может предложить электронному проекту?

Шаг 1. Зачем нужна версия вашей электроники?

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

Отслеживание истории изменений в проекте кажется полезным для проектов электроники; Если вы допустили ошибку в принципиальной схеме или используете неправильную посадочную площадку компонента в компоновке печатной платы, было бы неплохо отслеживать, какие ошибки были допущены и какие исправления были реализованы в различных версиях проекта. Другим создателям также было бы полезно увидеть эту историю и понять контекст и мотивы различных изменений.

Шаг 2. Инструменты: KiCad и Git

В этом проекте мы используем два основных инструмента: систему контроля версий (VCS) и программу автоматизации проектирования электроники (EDA или ECAD).

Существует МНОГО систем контроля версий, но мы используем распределенный VCS Git. Мы используем его по ряду причин, но ключевыми являются то, что он с открытым исходным кодом (проверьте!), Прост в использовании (проверьте!) И де-факто стандартная VCS для программного обеспечения с открытым исходным кодом (проверьте!). Мы будем использовать Git в качестве VCS для отслеживания изменений в файлах, которые использует наша программа ECAD. Для этого руководства не требуется знакомство с Git, но предполагается, что в целом удобство использования командной строки предполагается. При необходимости я постараюсь предоставить ссылки на полезные ресурсы как для Git, так и для командной строки.

Большинство систем управления версиями особенно хорошо работают с текстовыми файлами, поэтому программа ECAD, использующая текстовые файлы, была бы отличной. Представляем KiCad, «кроссплатформенный пакет автоматизации проектирования электроники с открытым исходным кодом», поддерживаемый исследователями из CERN. KiCad также имеет открытый исходный код (проверьте!), Прост в использовании (хотя некоторые не согласятся со мной по этому поводу) и хорошо подходит для сложных работ по проектированию электроники.

Шаг 3: установка

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

• KiCad является кроссплатформенным (и головокружительно; на их странице загрузки перечислены 13 поддерживаемых ОС и предлагается загрузить исходный код, если ни одна из них вам не подходит). Используйте стандартную установку kicad-unified, а не ночную разработку. См. Шаг 4 для дополнительных дополнительных сведений об установке библиотеки.
• Git также кроссплатформенный. Если вы используете Windows, я бы порекомендовал впечатляющий проект Git for Windows для более полезной и полнофункциональной работы.

Документация по установке, доступная на обоих этих сайтах, будет более полной, чем любое описание, которое я могу предложить здесь. После загрузки и установки обеих программ вы можете клонировать шаблон проекта Brainbow из нашего репозитория Github. Команда git clone принимает структуру `git clone {src directory} {target directory}`; для нашего проекта используйте `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Клонирование репозитория git - это особая форма копирования; когда вы клонируете проект, вы получаете копию всех файлов, включенных в репо, а также всю историю проекта, отслеживаемую Git. Клонируя наше репо, вы получаете каталог проекта, уже структурированный с нашими рекомендациями по использованию Git с KiCad. Мы расскажем больше о структуре проекта на шаге 6, или вы можете перейти к шагу 7, если вам не терпится приступить к работе.

Несколько быстрых служебных задач - запустите `git remote rm origin`, чтобы удалить ссылку на проект Github, из которого вы клонировали. Также запустите `git commit --amend --author =" John Doe "`, заменив параметр author своим именем и адресом электронной почты. Это изменяет последнюю фиксацию (которая в данном случае также является первой фиксацией) и меняет автора на вас, а не на Brainbow.

Шаг 4: Примечание по установке: библиотеки KiCad

Одно небольшое замечание о структуре библиотеки KiCad. KiCad предоставляет набор библиотек, поддерживаемых командой разработчиков, для широкого спектра электрических компонентов. Есть три основных библиотеки:

• Схематические символы: символы, используемые для представления электронных компонентов на принципиальном чертеже.
• Посадочные места печатной платы: 2D-чертежи, представляющие фактическую посадочную поверхность (медные площадки, шелкографию и т. Д.), Которые будут использоваться при компоновке схемы на печатной плате.
• 3D-модели: 3D-модели электронных компонентов.

Эти библиотеки загружаются вместе с только что установленным программным пакетом KiCad. Вы можете использовать KiCad без дополнительных усилий. Однако для «опытных пользователей» исходные файлы для библиотек хранятся в репозитории git на Github, что позволяет пользователям, которые хотят быть в курсе последних изменений, клонировать репозиторий библиотеки на свой компьютер. Отслеживание библиотек с помощью git имеет ряд преимуществ - вы можете выбрать, когда вы хотите обновить свои библиотеки, и обновления должны включать только изменения в файлах, а не загружать весь набор файлов библиотеки снова. Однако вы несете ответственность за обновление библиотек, о чем можно легко забыть.

Если вы хотите клонировать библиотеки, на этом сайте подробно описаны различные репозитории Github, которые предлагает KiCad. Git клонирует библиотеки на ваш компьютер (например, `git clone https:// github.com / KiCad / kicad-symbols.git`), затем откройте KiCad, выберите в строке меню пункт« Настройки »и нажмите« Настроить пути… . Это позволяет указать KiCad путь к каталогу для поиска каждой библиотеки. Эти переменные среды по умолчанию соответствуют пути к библиотекам, установленным при установке KiCad; Я записал эти значения, чтобы при необходимости вернуться к библиотекам по умолчанию. Путь KICAD_SYMBOL_DIR должен указывать на вашу клонированную библиотеку символов kicad, KISYSMOD - на клонированную библиотеку kicad-footprints, а KISYS3DMOD - на клонированную библиотеку kicad-packages3d.

Если вы хотите обновить библиотеки, вы можете запустить простую команду `git pull` в репозитории библиотеки, которая сообщит Git о необходимости проверки различий между вашей локальной копией репозитория библиотеки и« удаленным »репозиторием Github и автоматически обновить ваш локальная копия для внесения изменений.

Шаг 5. Основы Git

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

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

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

Шаг 6: Структура проекта KiCad

Давайте подробнее рассмотрим структуру проекта KiCad-Starter, который вы клонировали ранее. Для упрощения организации он разделен на несколько подкаталогов:

• Circuit: Эта папка содержит актуальные файлы проекта KiCad (схемы, печатные платы и т. Д.). Я не переименовываю эту папку, но я переименовываю все файлы внутри с именем проекта (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: файл проекта KiCad
  • Circuit.sch: файл схемы KiCad.
  • Circuit.kicad_pcb: файл компоновки печатной платы KiCad.
• Документация: эта папка предназначена для хранения документации по проекту. У нас есть планы по улучшению этого пространства в будущем, но пока он содержит простой файл README. Используйте его для хранения заметок о проекте, которые вы можете просмотреть в будущем.
• Изготовление: в этой папке вы будете хранить файлы gerber, которые большинство фабрик будут использовать для изготовления вашей печатной платы. Мы также используем его для хранения файлов спецификации и других документов, которые могут потребоваться для производства и сборки.
• Библиотеки: эта папка предназначена для хранения файлов библиотеки для конкретного проекта (мы рассмотрим это подробнее в нескольких шагах).

Вы также могли заметить несколько других файлов (особенно, если вы указали каталог с помощью ls -a). Каталог.git - это то место, где Git творит чудеса, храня историю репозитория. Файл.gitignore используется, чтобы сообщить Git, какие файлы следует игнорировать и не хранить в системе управления версиями. В основном это файлы резервных копий, которые генерирует KiCad, или несколько различных «сгенерированных» файлов, таких как списки соединений, которые не должны храниться в системе управления версиями, поскольку они генерируются из источника, которым является файл схемы.

Эта структура проекта - только отправная точка. Вы должны адаптировать его под свои нужды и добавлять разделы по мере необходимости. В некоторые проекты мы включали папку с программным обеспечением или папку корпуса, где мы хранили модели корпусов для 3D-печати для этого проекта.

Шаг 7. Использование Git для проектов KiCad

Наконец-то мы готовы посмотреть, как использовать Git для отслеживания ваших проектов. Это руководство не предназначено для того, чтобы научить вас использовать KiCad (хотя я могу сделать это в будущем, если на него будет спрос), поэтому мы рассмотрим несколько тривиальных примеров, чтобы показать вам, как работает рабочий процесс. Должно быть легко понять, как адаптировать эти идеи к реальному проекту.

Откройте каталог kicad-starter, затем запустите `git log`, чтобы просмотреть историю коммитов. Здесь должен быть один коммит, инициализация репо с помощью Brainbow. Запуск `git status` сообщит вам статус файлов в вашем репо (неотслеживаемые, измененные, удаленные, поставленные).

На данный момент у вас не должно быть никаких изменений в вашем репо. Давайте внесем изменения. Откройте проект KiCad и добавьте резистор в схему, затем сохраните. Теперь запуск `git status` должен показать, что вы изменили файл схемы, но еще не подготовили эти изменения для фиксации. Если вам интересно, что именно сделал KiCad, когда вы добавили резистор, вы можете запустить команду diff для измененного файла `git diff Circuit / Circuit.sch`. Это выделит изменения между текущей версией файла в рабочем каталоге и состоянием файла при последней фиксации.

Теперь, когда мы внесли изменение, давайте попробуем зафиксировать это изменение в истории нашего проекта. Нам нужно переместить изменения из нашего рабочего каталога в промежуточную область. На самом деле это не перемещает файлы в файловой системе, но концептуально является способом сообщить Git, что вы внесли все запланированные изменения в конкретный файл и готовы зафиксировать эти изменения. К счастью, Git предоставляет некоторые подсказки, когда вы запускаете `git status` для следующего действия. Обратите внимание на сообщение `(используйте« git add… », чтобы обновить то, что будет зафиксировано)« в разделе «Изменения, не предназначенные для фиксации:». Git сообщает вам, как переместить изменения в промежуточную область. Запустите `git add Circuit / Circuit.sch`, чтобы внести изменения, затем` git status`, чтобы увидеть, что произошло. Теперь мы видим, что в файле схемы есть изменения, которые необходимо зафиксировать. Если вы еще не хотите фиксировать эти изменения, Git предлагает еще один совет: `(используйте« git reset HEAD… »для отмены сценария)`. Мы действительно хотим зафиксировать эти изменения, поэтому запускаем `git commit -m" Добавлен резистор в схему ". Это фиксирует изменения с предоставленным сообщением. Запуск git log покажет этот коммит в истории коммитов проекта.

Еще несколько советов по поводу коммитов.

1. Не совершайте каждое сохранение. Зафиксируйте, когда почувствуете, что достигли точки, в которой ваши изменения несколько укрепились. Я совершаю фиксацию после завершения схемы, а не после добавления каждого компонента. Вы также не хотите совершать коммит слишком редко, потому что может быть сложно вспомнить контекст, в котором вы внесли изменения, которые сделали через 3 недели. Выяснить, когда делать коммит, - это немного искусство, но вам станет удобнее по мере того, как вы будете больше использовать Git.
2. Только исходники магазина (в основном). Сюда входят файлы проекта, схемы и макета, а также библиотеки для конкретного проекта. Это также может включать файлы документации. Будьте осторожны при сохранении производных объектов, потому что они могут легко рассинхронизироваться с исходным источником, что впоследствии вызовет головную боль. Файлы спецификации и герберы особенно легко десинхронизируются, поэтому их лучше избегать (хотя более подробные инструкции описаны в шаге 9).
3. Сообщения о фиксации очень полезны, но хорошо структурированные сообщения о фиксации бесценны. В этой отличной статье приведены некоторые рекомендации по написанию четких, кратких и полезных сообщений о фиксации. Для этого может потребоваться использование текстового редактора командной строки, что может показаться сложным для новичков (`git commit` без опции -m message откроет текстовый редактор). Большинству людей я рекомендую редактор Nano. У StackOverflow есть хорошее объяснение смены редактора

Шаг 8: Дополнительно: семантическое управление версиями для электроники

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

В программном обеспечении существует концепция семантического управления версиями (semver). Semver определяет общую методологию именования для идентификации выпусков программного обеспечения по «номеру версии», следуя шаблону «Major. Minor. Patch». Чтобы процитировать спецификацию semver, вы увеличиваете номер версии в соответствии со следующими категориями изменений.

1. ОСНОВНАЯ версия при внесении несовместимых изменений API,
2. МИНИМАЛЬНАЯ версия, когда вы добавляете функциональность обратно совместимым образом,
3. Версия PATCH при исправлении ошибок с обратной совместимостью.

Мы в Brainbow используем нашу собственную версию semver, адаптированную под нужды аппаратных проектов. Наша спецификация следует той же схеме «Major. Minor. Patch», хотя наши определения того, какие изменения попадают в какую категорию, явно различаются.

1. ОСНОВНАЯ версия: используется для значительных изменений основных функций схемы (например, переключение процессора с ATmegaa на ESP8266).
2. МИНИМАЛЬНАЯ версия: используется для замены компонентов, которые могут повлиять на работу схемы (например: замена флэш-памяти SPI на совместимую по выводам деталь, которая может иметь другой набор команд) или для добавления некоторой незначительной дополнительной функции (например, добавлен дополнительный датчик температуры).
3. Версия PATCH: используется для мелких исправлений, которые не меняют работу схемы (например, настройка шелкографии, настройка компоновки незначительных трасс, простая замена компонентов, например, конденсатор 0603 на 0805).

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

Помимо преимуществ в согласованности и понятности, которые вы получаете от перехода на четко определенную систему именования, вы также получаете преимущества в совместимости с микропрограммным обеспечением и удовлетворенности клиентов. Прошивка может быть написана с учетом версии платы, на которую она нацелена, и может быть проще отладить, почему конкретная программа не работает на конкретной плате («верно, прошивка 2.4.1 не работает на 1.2. доски, потому что у нас нет… »). Заказчики также извлекли выгоду из нашего аппаратного семвера, потому что обслуживание клиентов и устранение неисправностей намного проще с определенным стандартом.

Шаг 9: Дополнительно: использование аппаратного семантического управления версиями

Чтобы использовать аппаратный семвер в ваших собственных проектах, мы используем функцию Git, называемую тегированием. Когда вы впервые производите плату, это версия этой платы 1.0.0. Убедитесь, что вы зафиксировали все изменения в своем проекте, затем запустите `git tag -a v1.0.0`. Откроется редактор, в котором вы сможете написать аннотацию для этого тега (очень похожую на сообщение фиксации). Я включаю подробности о производстве (кто изготовил печатную плату, кто собирал плату), которые могут быть полезны позже.

Тег выпуска добавляется в историю фиксации и указывает состояние файлов при изготовлении 1.0.0. Это может быть особенно полезно через несколько версий позже, когда вам нужно будет вернуться к этому пункту для устранения неполадок. Без указанного тега выпуска может быть сложно определить, какая фиксация была последней на момент изготовления. Тег 1.0.0 (и 1.1, 1.1.1 и т. Д.) Позволяет указать, что именно эти исходные файлы использовались в конкретном производственном цикле.

Заметка о герберах. Некоторым фабричным домам для изготовления доски требуются файлы gerber, и вы можете создавать их с помощью KiCad. Это производные объекты, созданные из исходного файла.kicad_pcb, и мы обычно не используем производные файлы для управления версиями. Мы в Brainbow не храним герберы в системе контроля версий, ЗА ИСКЛЮЧЕНИЕМ тех случаев, когда мы помечаем выпуск. Когда мы готовы к сборке, мы генерируем файлы gerber, сохраняем их в папке Fabrication, фиксируем и помечаем. Затем мы удаляем герберы и фиксируем удаление. Сначала это может показаться немного запутанным, но это гарантирует, что обычные коммиты сохраняют только исходные файлы, а помеченные релизы также сохраняют точные файлы, используемые для производства плат. Это оказалось чрезвычайно полезным для отслеживания производственных ошибок через несколько недель.

Шаг 10: Дальнейшие действия

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

Brainbow работает над более подробным руководством по некоторым из наиболее продвинутых функций нашего рабочего процесса. Мы надеемся опубликовать его в ближайшие несколько месяцев. Следуйте за нами здесь, в Instructables, и мы обязательно сообщим вам, когда вы сможете это прочитать.

Спасибо за чтение, и нам не терпится увидеть, что вы делаете!