Мой Git, мои правила
Краткая выдержка из личной практики
Оформление комментариев к коммитам
Ниже простые, но эффективные правила для создания комментариев к гит-коммитам
- Нет ничего зазорного в том, чтобы в комментариях использовать русский язык.
- В описании отвечайте на вопрос «Что сделать? и Зачем это делать?» против «Как это сделано?» Помните, что назначение комментария — дать вашим коллегам понять, что происходит в проекте. Поставьте себя на место читателя и подумайте, как лучше охарактеризовать зачем был сделан этот коммит.
- Не поддавайтесь слабости написать «дурацкие баги» или «исправил проблему», старайтесь максимально четко и ясно написать что и зачем было сделано.
- Если коммит связан с какой-то внешней информацией (багом в редмайне, страницей в вики или чем-нибудь еще), то очень хорошей идеей будет явно указать это в комментарии к коммиту
- Не пишите что именно поменялось — это всегда видно по диффам. Пишите зачем были внесены изменения. Это как раз то, что по диффам не видно. Старайтесь уместить первую строку в 60 символов — дополнительную информацию всегда можно написать отдельным параграфом после пустой строки.
- Будет полезным (желательным) указывать тип коммита, например, вот несколько типов коммитов, нагугленных за пару минут (их можно расширять и дополнять опираясь на специфику проекта):
- [feature] — используется при добавлении новой функциональности уровня приложения
- [fix] — если исправили какую-то серьезную багу
- [doc] — всё, что касается документации
- [rtl] — всё, относящееся к синтезируемомму коду
- [verif] — всё, относящееся к верификации (HW)
- [style] — исправляем опечатки, исправляем форматирование
- [refactor] — рефакторинг кода приложения
- [test] — всё, что связано с тестированием (SW)
- [chore] — обычное обслуживание кода
- Reserved for future insight ;-)
.gitignore
Гитхаб собирает коллекцию своих вариантов gitignore для популярного ПО, удивительно было найти в названиях файлов коллекции Xilinx, Synopsys, Virtuoso, Modelsim, MATLAB.
Лет 5 назад я предпринимал аналогичную попытку создать подобную коллекцию для разработчиков ASIC/FPGA, увы, сегодня понимаю тщетность усилий - это работает только внутри конкретного коллектива/флоу разработки: слишком много нюансов и степеней свободы. Кто-то файлы проектов/скриптов синтеза не пишет вручную, а каждый раз пересоздаёт в рантайме (и как любой нерукотворный труд - не кладёт в гит), кто-то в соответствии с корпоративным флоу помещает в гит edif/verilog-нетлисты независимых IP-блоков (или даже дампов моделирования).
Одним словом для ASIC и FPGA универсальной пилюли .gitignore не существует, каждый шаблон необходимо обтёсывать (в т.ч. при смене работодателя), но есть позитив - эти изменения обычно минорны и шаблоны таки скорее полезны чем нет.
.gitattributes
Нередко замечал что гитхаб неправильно определяет языки исходников, но считал, что это от рождения и не поддаётся лечению (особенно расстраивало игнорирование кастомных расширений вроде *.vh для инклюд-файлов верилога).
Так вот оказывается у гитхаба есть собственное расширение синтаксиса gitattributes для правильного анализа языков и можно его “обучить” правильному детекту.
Т.о. проблема с *.vh лечится одной строчкой в .gitattributes
*.vh linguist-language=Verilog
Также можно указывать пути, которые будут игнорироваться при анализе языка исходников (документация и сторонние/другого автора библиотеки).
Полезная, но неочевидная фича гитхаба
Оказывается можно применить дополнительный фильтр, выведя только те репо, в которых основным языком будет являться заданный в запросе, просто дописав URL.
Фильтр для применения к аккам организаций: ?language=
Фильтр для применения к аккаунтам пользователей: tab=repositories&language=
Пример использования:
PS: verilog & systemverilog - разные языки по логике гитхаб.
