Conventional-Hardware-Versioning v1.1.0

Соглашение о версионировании проектов при разработке аппаратного обеспечения

Соглашение версионирования

Версионирование проектов АО¹ по системе, основанной на семантическом версионировании для ПО². Вид номера версии: Major.Minor.Build-Prerelease+Meta

Major

Изменение Major-версии говорит о том, что изменились функциональность продукта (платы/устройства/изделия) или его технический интерфейс³ (т.е. состояние входов-выходов, форм-фактор и т.п.) или и то и другое.

При увеличении Major-версии Minor и Build обнуляются. Изменение Major-версии касается платы и КД. Обязательно выпускается новая плата.

Возможные изменения для Major-версии:

1. Изменение размеров, форм-фактора, контура платы
2. Перемещение/удаление/добавление/изменение крепежных отверстий
3. Изменение толщины или материала платы
4. Добавление/изменение/удаление/перемещение разъёмов
5. Изменение цоколёвки разъёмов
6. Добавление/удаление/изменение интерфейсов. Например, добавление Ethernet, добавление GPIO, удаление RS-485 и т.п.
7. Замена ключевых компонентов, таких как МК
8. Добавление/удаление функциональности. Например, добавление датчика температуры или удаление микросхемы-акселерометра и т.п.
9. Добавление схемы защиты питания/входа/выхода

Minor

Изменение Minor-версии говорит о том, что в продукт внесены изменения, но при этом его функциональность и технический интерфейс сохранены.

При увеличении Minor-версии Build обнуляется. Изменение Minor-версии касается платы и КД. Обязательно выпускается новая плата.

Возможные изменения для Minor-версии:

1. Изменение, доработки трассировки
2. Исправление ошибок трассировки
3. Доработки или исправление ошибок на слоях шелкографии и т.п.
4. Изменение посадочного места компонента. Например, замена резистора 0805 на 1206 или м/с в корпусе SOIC-8 на такую же в корпусе DIP-8 и т.п.
5. Исправление ошибок посадочных мест
6. Исправление прочих ошибок
7. Перенос проекта на другую САПР

Если две платы имеют номера, например, v1.2 и v1.3, это значит, что функционально они идентичны, но в версии 1.3 есть некоторые изменения с целью возможного улучшения функционирования или исправления ошибок (например, улучшена трассировка, откорректирована шелкография, микросхема памяти заменена на аналогичную в другом корпусе). Предпочтительнее в новых сборках использовать более позднюю версию.

Build

Build-версия релиза отражает конкретную сборку на плате версии vMajor.Minor.

Build отражает доработки и альтернативные варианты изделия, которые реализуются на одной из уже выпущенных версий платы (исполнения изделия). Изменения вносятся на уже существующую плату и затрагивают КД. Новая плата не выпускается.

Возможные изменения для Build-версии:

1. Различные исполнения изделия, существующие параллельно. Один из вариантов исполнения принимается за основной. Исходный номер Build-версии для этого варианта будет равен 0. Например, исполнения DC-DC преобразователя с разными выходными напряжениями, которые можно задать путём установки соответствующих резисторов в делитель ОС. Отличия будут только в спецификации и перечне элементов, схема и плата остаются без изменений. Допустим, что основное исполнение с выходным напряженим 12 В имеет номер версии v1.3.0. Версии для других исполнений могут быть, например, v1.3.1 - для выходного напряжения 15 В и v1.3.2 - для 24 В
2. Доработки изделия на существующей плате:
   1. Без вмешательства в трассировку:
      1. Добавление новых связей проводными перемычками
      2. Исключение компонента с платы (отметка в КД "не устанавливать")
      3. Изменение номинала компонента, который устанавливается на уже существующее посадочное место. Например, резистор 0805 2 кОм заменён на 0805 3,3 кОм
      4. Установка компонента, для которого нет посадочного места на плате, между выводами разъёма или микросхемы "навесным" способом (например, добавление защитного диода или фильтрующего конденсатора) и т.п.
   2. Путём вмешательства в трассировку: удаление связей путём разрезания дорожек

Если были внесены изменения второго типа (доработка), вероятнее всего их потребуется выполнить также для всех исполнений, поскольку доработки, как правило, вносятся для улучшения работы изделия, добавления защиты, исправления ошибок и т.п. Однако, это может потребоваться не всегда. Допустим, для примера выше (исполнения для различных выходных напряжений DC-DC преобразователя), была внесена доработка - добавлен конденсатор для улучшения фильтрации. Данную доработку требуется внести для всех исполнений - 12, 15 и 24 В. Тогда новые версии будут следующими: v1.3.3 - 12 В плюс конденсатор, v1.3.4 - 15 В плюс конденсатор, v1.3.5 - 24 В плюс конденсатор.

Внесение доработок в репозиторий

При внесении доработок в изделие, их необходимо зафиксировать в репозитории и документации.

В редакторе платы САПР отметки о доработках выполняются на отдельном слое. Например, F.Revision и B.Revision. Вся КД должна быть обновлена, если доработка требует внесения изменений в данный документ.

Доработки также следует зафиксировать на фото и зафиксировать фото в репозитории.

Пояснение для изделий без печатных плат (навесной монтаж). Над данным разделом ещё следует подумать!

Для изделий, не имеющих в своём составе печатных плат, логика версионирования глобально остаётся такой же, за исключением того, что некоторые пункты из Build-версии переходят в Minor. Поскольку плата отсутствует, и, например, изменения связей (добавление/удаление) и так по-умолчанию выполняются проводами, поэтому это сразу приводит к изменению Minor-версии.

Build-версия же по сути остаётся только для отображения исполнений изделия и изменений, касающихся только КД (например, изменение номинала компонента).

1. Изменения форм-фактора изделия, какие-либо манипуляции с входным-выходным интерфейсом (перемещение/удаление/добавление/изменение разъёмов, изменение протоколов и т.п.), замена ключевых компонентов, изменение функциональности, изменение защит приводит к увеличению Major-версии
2. Внесение различных улучшений, не изменяющих основной функциональности изделия, исправление ошибок, изменения "трассировки" (перемещение/удаление/добавление контактных колодок для пайки, изменение связей проводами), удаление компонентов, замена "корпусов" компонентов и т.п. приводит к увеличению Minor-версии
3. Исполнения изделия

Предварительный релиз (Pre-release)

Предварительные релизы указывают на стадию разработки, в которой находится данная версия продукта. Предварительный релиз добавляется после основного номера версии, разделяется от него знаком минус.

Возможные варианты предварительных релизов (в порядке следования):

1. proto, pt - подготовлены файлы для изготовления прототипа платы вручную (любым доступным способом). Релиз этого типа нужен для того, чтобы однозначно зафиксировать выходные файлы, на основании которых изготовлен прототип. Прототип изготавливается минимум в одном экземпляре (может быть несколько).
2. rc (release candidate) - подготовлены файлы для производства платы на заводе (плата заказана). Релиз этого типа нужен для того, чтобы однозначно зафиксировать выходные файлы, на основании которых изготовлены платы.
3. docprod, dp (document production) - версия изготовлена, базовый функциональный тест пройден, идёт процесс разработки, уточнения, согласования и утверждения комплекта КД.

Метаданные

Метаданные могут содержать любую необходимую дополнительную информацию. Метаданные включаются в конец строки с номером версии и отделяются знаком плюс.

Метаданные обязательно включают дату выпуска релиза в формате YYYY.MM.DD или YYYY-MM-DD.

Обобщение

Номера версии Major и Minor изменяются только при выпуске новой платы (партии плат) и уникально идентифицируют версию платы как детали.

Полная же версия Major.Minor.Build уникально идентифицирует версию платы как сборочной единицы, то есть конкретную сборку.

Предварительные релизы нужны для того, чтобы отмечать стадии разработки (прототипирование, сборка и базовое функциональное тестирование, утверждение документации и т.п.).

Метаданные содержат дату выпуска релиза, также могут содержать другую полезную информацию.

Информация о версии, наносимая на плату

При производстве платы на слоях меди или шелкографии:

• Версия платы (Major и Minor части номера релиза): vX.Y.
• Дата разработки релиза платы: YYYY.MM.DD
  • Если места недостаточно, допустимо использовать сокращённые форматы даты (YYYY.MM или MM.YY) После номера версии vX.Y. на плате оставляется свободное поле для нанесения Path-номера версии вручную позже.

Примечание для проектов на работе

В связи с особенностями ведения изменений на работе

Изменение платы

Поскольку на работе изменение платы помечается уникальным номером, состоящим из одного числа (а "нулевое" изменение вообще не помечается), для указания соответствия git-релиза проекта номеру изменения платы в тег релиза добавляются метаданные (после даты): pcbN, где

• N - номер изменения по системе, принятой на работе.

Изменение КД

Изменение КД добавляется к тегу в метаданные (после даты и изменения платы): docN-MM.YY, где

• N - номер изменения КД
• MM.YY - дата выпуска КД (месяц, год) Возможны ситуации, когда изменения в КД вносятся вручную, указывается дата изменения, при этом основной номер изменения КД не меняется. Т.е. наличие двух тегов c одинаковыми номерами изменения, но разными датами - это нормальное явление, и означает, что изменение внесено вручную указанной датой для сохранения истории (например, doc.0-12.23; doc.0-03.25).

Релиз

Новый релиз создаётся при реальном изготовлении новой версии платы и/или новой сборки проекта (хотя бы в единственном экземпляре).

Релиз	Плата	Сборка	Базовый функциональный тест	КД
Прототип (pt, proto)	Подготовлены файлы для производства прототипа платы. Возможно плата изготовлена вручную	Может быть выполнена	Может быть пройден	Может иметься проект рабочей документации
Кандидат (rc)	Подготовлены файлы для производства платы. Возможно плата изготовлена	Может быть выполнена	Может быть пройден	Не утверждена. Может иметься проект рабочей документации, но она не проверена и не утверждена, может содержать ошибки
Утверждение КД (dp, docprod)	Изготовлена	Выполнена	Пройден успешно	Не утверждена. Идёт процесс разработки, согласования и утверждения
Основной	Изготовлена	Выполнена	Пройден успешно	Утверждена

Гарантии релизов:

• Прототип (pt, proto) - наличие выходных файлов для изготовления прототипа платы.
• Кандидат (rc) - наличие выходных файлов для изготовления плат на заводе.
• Утверждение КД (dp, docprod) - существование хотя бы одной сборки, которая прошла базовый функциональный тест.
• Основной релиз - существование хотя бы одной сборки, которая прошла базовый функциональный тест; наличие полного комплекта КД на данную версию.

В системе Git релиз помечается тегом.

В файле описания проекта при наличии нескольких предварительных релизов информация указывается для последнего. Пояснения по предварительным релизам может содержаться в описании релиза.

Пример

Когда версия платы готова к релизу, сначала для проверки она изготавливается вручную, например, методом фоторезиста. Для этого в проекте подготавливаются необходимые файлы для выпуска, в данном случае это файлы фотошаблонов медных слоёв. После вывода из САПР данных файлов, текущее состояние проекта фиксируется коммитом, в который также добавляются и файлы фотошаблонов. Данный коммит помечается тегом версии-прототипа, например: v1.0.0-pt+2024.03.12.

Далее по выпущенным фотошаблонам изготавливается плата и собирается прототип. Допустим, прототип успешно запустился и прошёл тесты, изменения в плату не были внесены. Значит, можно переходить к следующей стадии. Подготавливаются гербер-файлы и файлы сверловки и фиксируются коммитом. Коммит помечается тегом релиз-кандидата, например: v1.0.0-rc+2024.03.20. Теперь платы могут быть заказаны на заводе.

После изготовления плат на заводе собирается опытный образец/образцы на данной версии платы. Затем образец проходит базовый функциональный тест. Предположим, что после сборки и проверки были выполнены ещё некоторые доработки и заказаны новые платы. Коммит с новыми производственными файлами помечается тегом релиз-кандидата аналогично предыдущему пункту, но к надписи rc добавляется номер 1, например: v1.0.0-rc1+2024.04.08.

Далее снова заказываются новые платы, изготавливаются образцы и выполняется базовый функциональный тест. Если тест успешно выполняется, разрешается переход к стадии утверждения документации. Номер версии может выглядеть так: v1.0.0-dp+2024.03.28.

После редактирования и утверждения документации выпускается окончательная версия (основной релиз), например: v1.0.0+2024.04.05.

Если прототип не изготавливался, предварительный релиз типа pt, proto не выпускается. Если документация были сделана и утверждена параллельно со сборкой и базовым функциональным тестированием, релиз типа dp, docprod не выпускается, а сразу после релиз-кандидата выпускается основной релиз.

Релиз-кандидат обязательно следует выпускать при реальном изготовлении плат (заказе на заводе) для фиксации производственных файлов, по которым будет изготовлена плата, и однозначном их соответствии реально изготовленной плате данной версии.

Ресурсы

1. Version Control for Open Source Hardware
2. Система контроля версий для hardware (статья на Хабре)
3. Семантическое версионирование 2.0.0
4. HW-Versioning-Rule-Book (github)

Footnotes

1. АО - аппаратное обеспечение ↩

2. ПО - программное обеспечение ↩

3. Технический интерфейс - описание продукта (платы/устройства/изделия) как "чёрный ящик", включающее спецификацию электромеханических характеристик (габариты, форм-фактор платы, расположение разъёмов, индикаторов, описание входных и выходных интерфейсов и т.п.) в достаточной мере для использования изделия. ↩