Привет, хабр! Моя прошлая статья об химии в Python рассказывает о том, как написать простой калькулятор молекулярной массы.
Сегодня мы затронем сторону, отличную от написания кода. Мы займемся оформлением и написанием документации, как правильно делать коммиты и как оформлять код.
Все, что вы увидите в данной статье, будет касаться прочитанных мною материалов и полученного опыта.
В мире разработки программного обеспечения правильное оформление документации играет ключевую роль в обеспечении ясности и понятности проекта. Особенно важным этапом в этом процессе является создание и поддержание README файлов в Git репозиториях. README файлы - это первое, что увидит разработчик, приступая к работе с проектом, и хорошо оформленная документация может значительно упростить процесс взаимодействия с кодом.
В данной статье мы рассмотрим ключевые аспекты оформления документации в Git репозитории, обсудим лучшие методики и практики для создания качественной документации. Независимо от того, являетесь ли вы опытным разработчиком или новичком в области Git, эта статья поможет вам создать четкую, структурированную и информативную документацию для вашего проекта. Погружайтесь в мир оформления документации, улучшайте ваши проекты и делитесь своими идеями с сообществом разработчиков Хабр!
Почему документация тоже важна?
Документация поможет пользователям и разработчикам. Да, если им сильно нужно - они могут и просто скачать или почитать код, но многих отсутствие нормальной документации или хотя-бы нормального README файла отпугивает. Что вы бы выбрали - хорошо заполненный и документированный репозиторий или такой же репозиторий, но без какой либо информации? Я думаю, ответ очевиден.
Да и вам может помочь хорошее оформление кода и документации, если вы вдруг вернетесь к проекту, и не захотите воскликнуть "Что за китайская тарабарщина! Какой идиот это писал? А, это я...".
Как оформить README файл
Я не буду рассказывать, как зарегистрироваться на гитхабе, что это такое и зачем. Эта статья не об этом.
Допустим, вы уже создали свой репозиторий. Главное - это изменить или создать README файл. Но что это такое? README - это файл, обычно в формате txt или md (мы будем использовать md, это markdown, язык разметки), в котором содержится базовая информация о проекте.
Вот пример README из моего репозитория
# Oxygen
Программное обеспечение для инженерных вычислений, научно-естественных наук, математики и алгоритмов <!-- описание репозитория -->
<!--Блок информации о репозитории в бейджах-->
<!--Установка-->
## Установка (Linux)
У вас должны быть установлены [зависимости проекта](https://github.com/OkulusDev/Oxygen#зависимости)
1. Клонирование репозитория
```git clone https://github.com/OkulusDev/Oxygen.git```
2. Переход в директорию Oxygen
```cd Oxygen```
3. Создание виртуального окружения
```python3 -m venv venv```
4. Активация виртуального окружения
```source venv/bin/activate```
5. Установка зависимостей
```pip3 install -r requirements.txt```
6. Запуск скрипта для демонстрации возможностей Oxygen
```python3 oxygen.py --help```
<!--Пользовательская документация-->
## Документация
Пользовательскую документацию можно получить по [этой ссылке](./docs/ru/index.md).
[Релизы программы]: https://github.com/OkulusDev/Oxygen/releases
<!--Поддержка-->
## Поддержка
Если у вас возникли сложности или вопросы по использованию пакета, создайте
[обсуждение](https://github.com/OkulusDev/Oxygen/issues/new/choose) в данном репозитории или напишите на электронную почту <bro.alexeev@inbox.com>.
<!--зависимости-->
## Зависимости
Эта программа зависит от интепретатора Python версии 3.7 или выше, PIP 23.2.1 или выше. Если вы заметили, что он данное ПО можно запустить на версии ниже, или он не работает на какой-либо версии, то напишите в [поддержку](https://github.com/OkulusDev/Oxygen#поддержка)
<!--описание коммитов-->
## Описание коммитов
| Название | Описание |
|----------|-----------------------------------------------------------------|
| build | Сборка проекта или изменения внешних зависимостей |
| sec | Безопасность, уязвимости |
| ci | Настройка CI и работа со скриптами |
| docs | Обновление документации |
| feat | Добавление нового функционала |
| fix | Исправление ошибок |
| perf | Изменения направленные на улучшение производительности |
| refactor | Правки кода без исправления ошибок или добавления новых функций |
| revert | Откат на предыдущие коммиты |
| style | Правки по кодстайлу (табы, отступы, точки, запятые и т.д.) |
| test | Добавление тестов |
В самом вверху, при помощи знака #, что означает заголовок первого уровня, мы обозначаем название программы.
Потом идет краткое описание программы.
Ниже - уже поинтереснее. Там вы видите ссылки на изображения-бейджи, которые оповещают, что за репозиторий, какой здесь используется в основном язык, и т.д и т.п. В самом низу этого блока мы видем ссылку на другое изображение - логотип нашего репозитория, ссылка которого уже локальная, сам логотип хранится в папке docs
Под этими бейджами мы видем инструкцию по установке и запуске репозитория. Желательно, он должен расписан поэтапно.
Дальше мы видем блок с ссылкой на пользовательску документацию и релизы. К этому мы вернемся позже.
Под ссылками на документацию мы ввидем блок поддержки, то есть там информация о контактах разработчика и ссылка на создание issue.
Далее идут зависимости. Там мы должны перечислить, что будет нужно установить пользователю.
И в конце - описание коммитов. Вы можете не вставлять их, но я вставляю. Это таблица, в которой хранятся типы коммитов. О них мы сейчас и поговорим.
Коммиты
Коммиты - это заявки, ссылки на обновление репозитория, грубо говоря. И при создании коммита мы должны указывать сообщение. И этого также много значит.
Название типа коммита |
Описание |
build |
сборка проекта или внешних зависимостей |
sec |
обновления безопасности |
ci |
настройка CI и работа со скриптами |
docs |
обновление документации |
feat |
добавление нового функционала |
fix |
исправление ошибок |
perf |
изменения, направленные на улучшения производительности |
refactor |
правки кода без исправления ошибок или добавления новых функций |
revert |
откат на предыдущую версию, предыдущие коммиты |
style |
правки по стилю кода |
test |
добавление тестов |
По правилам, коммит должен быть в повелительном наклонении, потому что это, как бы указание разработчику, что надо делать
git commit -m "feat: add line output" # en, добавьте вывод строки
git commit -m "feat: добавьте вывод строки" # ruПользовательская документация
Чтобы создать ее, нам нужно в корневом каталоге создать каталог docs, а в нем подкаталог ru (получиться должно так: docs/ru)
Зачем нам создавать подкаталог ru в docs, когда все можно и без нее обойтись? Ответ прост - чтобы энтузиасты могли легко помочь нам с переводом документации на другой язык, просто создав новую подкаталог.
Создаем в docs/ru файл index.md с похожим содержанием:
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
## Оглавление
1. [Введение](./getting-started.md)
1. [Основы химии](./chemistry-basics.md)
## Описание коммитов
| Название | Описание |
|----------|-----------------------------------------------------------------|
| build | Сборка проекта или изменения внешних зависимостей |
| ci | Настройка CI и работа со скриптами |
| sec | Безопасность, уязвимости |
| docs | Обновление документации |
| feat | Добавление нового функционала |
| fix | Исправление ошибок |
| perf | Изменения направленные на улучшение производительности |
| refactor | Правки кода без исправления ошибок или добавления новых функций |
| revert | Откат на предыдущие коммиты |
| style | Правки по кодстайлу (табы, отступы, точки, запятые и т.д.) |
| test | Добавление тестов |
В этом файле мы вставляем заголовок и оглавление, а также на всякий случай описание коммитов
Далее мы просто создаем файлы для оглавления, саму документацию в markdown.
Вот пример файла getting-started.md:
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
### [Оглавление](./index.md)
## Введение
Проект Oxygen представляет собой мощное программное обеспечение, разработанное специально для инженерных вычислений, естественно-научных исследованиях, математики и алгоритмизации. Оно обеспечивает разработчиков инструментами, необходимыми для выполнения высокоточных вычислений и анализа данных.
Oxygen основан на передовых алгоритмах, использующихся в сфере инженерии и естественно-научных исследований. Это позволяет разработчикам решать сложные задачи эффективно и точно.
А вот пример файла chemistry-basics.md
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
### [Оглавление](./index.md)
## Основы химии
1. Что такое относительная атомная масса и молекулярная масса:
Относительная атомная масса (также известная как атомная массовая единица, amu) - это масса атома в единицах массы атома углерода-12. Она используется для измерения массы атомов и молекул.
Относительная молекулярная масса - это сумма относительных атомных масс атомов в молекуле. Она позволяет определить массу молекулы в отношении массы атома углерода-12.
2. Число Авогадро:
Число Авогадро равно приближенно 6.02214076 x 10^23 и представляет собой количество атомов или молекул в одном моле вещества. Это основная константа, используемая для связи массы атомов и молекул с массой вещества в молях.
3. Моли:
Моль - это единица измерения количества вещества. Один моль вещества содержит число Авогадро частиц (около 6.022 x 10^23) атомов, молекул или других элементарных частиц.
4. Металлы и неметаллы:
Металлы - это элементы, обладающие характерными свойствами, такими как отличная теплопроводность, проводимость электричества, металлический блеск и гибкость. Примеры металлов включают железо, медь и алюминий.
Неметаллы - это элементы, обладающие характеристиками, противоположными металлам. Неметаллы обычно плохо проводят тепло и электричество и могут быть хрупкими. Примеры неметаллов включают кислород, азот и серу.
5. Электроны, нейтроны и протоны:
Электроны - это элементарные частицы, обладающие отрицательным электрическим зарядом. Они находятся в орбиталях вокруг ядра атома.
Протоны - это элементарные частицы, обладающие положительным электрическим зарядом, и они находятся в ядре атома.
Нейтроны - это элементарные частицы, не имеющие электрического заряда, и они также находятся в ядре атома.
6. Заряд ядра и энергетические уровни:
Заряд ядра - это сумма зарядов протонов в атомном ядре, который определяет химические свойства элемента.
Энергетические уровни - это уровни энергии, на которых находятся электроны в атоме. Электроны находятся на определенных энергетических уровнях и могут переходить между ними, поглощая или испуская энергию в форме света (спектральных линий).
Ваша документация может быть другая, главное - чтобы она была, и желательно качественная.
Заключение
Документация и оформление репозитория - одни из самых главных задач для разработки хорошего ПО. Я надеюсь вам понравилась эта статья, и вы ее оцените!
Моя прошлая статья об химии в python
С вами был доктор Аргентум, до новых встреч, пока!
UPD: от Tryd0g0lik, генераторы
.gitignore - https://www.toptal.com/developers/gitignore/ - генератор
Git Command - https://gitexplorer.com/ - генератор синтаксиса
README - https://readme.so/ru - генератор
Комментарии (41)
ritorichesky_echpochmak
19.11.2023 13:05И этого также много значит
И этим всё сказано. Вчера увидел что github поддерживает markdown, но ещё не разобрался, поэтому каждый заголовок дублируется в ремарках. Заявки в повелительном наклонении репозиторию? - ну дичь же. Хватит это бездумно копировать, такая статья тут появляется каждый месяц и каждый раз в это тычут. Практического применения примерно ноль. Но если захочешь собрать, например, changelog через `git shortlog --no-merges master --not $(git describe --tags --abbrev=0)` выясняется, что его весь нужно переписывать.
| revert | Откат на предыдущие коммитыrevert не так работает, этот текст вводит в заблуждение
Вот эти огрызки feat, sec, refactor... что люди делают с сэкономленными буквами? Почему refactor можно написать, а feature - слишком длинно? Зачем вообще держать в тексте тысячи feature, если и так понятно что по умолчанию фичи пилишь?
DrArgentum Автор
19.11.2023 13:05-1Приветствую! Да, эта статья, моя вторая статья, вышла кривая, я уже это понял. Поддерживаю ваше мнение, но таких статей я еще мало видел, или я плохо искал. Спасибо за ваше мнение!
ritorichesky_echpochmak
19.11.2023 13:05Их регулярно скрывают обратно в черновики, потому что ну... грабли одни и те же, людям поднадоело, реакция соответствующая.
Главное правило к коммитам - писать их. Так, чтобы людям в удобной форме доносилось, что сделано в этом коммите. Можно соблюсти все формальности которые написаны в статье и иметь всё равно максимально плохо читаемые коммиты вида
```feat(core): update core
Solved #123 Look also #345 #678
```
И в итоге всё равно непонятно что делалось, зачем, что это за задачи подключены.
На реальных проектах зачастую у людей либо проговариваются правила оформления коммитов, либо вообще срабатывает автогенерация текста коммита по ID задачи (т.е. в заголовок коммита прописывается ID задачи и её заголовок)
delphinpro
19.11.2023 13:05+1Вот эти огрызки feat, sec, refactor... что люди делают с сэкономленными буквами? Почему refactor можно написать, а feature - слишком длинно?
Огрызки, очевидно для краткости. Своего рода текстовые бэйджики. А refactor и revert полностью, потому что сокращения будут скорее всего ассоциироваться с другими словами. Сокращение ref лично для меня интуитивно подразумевает reference, то есть ссылку, а rev - revision.
А вот про практический смысл этого я бы почитал, только чтобы аргументированно было написано, без натягивания совы.
solarplexus
19.11.2023 13:05Заявки в повелительном наклонении репозиторию? - ну дичь же.
Что именно дичь? Слово "заявка" или повелительное наклонение?
ritorichesky_echpochmak
19.11.2023 13:05Кому заявки и кому повелительное наклонение? Себе? QA (раз с твоей стороны таска закончена и ушла в CI/CD)? Кастомеру? Гитхабу? Копилоту на гитхабе?
DrArgentum Автор
19.11.2023 13:05Как я сказал уже в статье, повелительное наклонение - инструкция разработчику, себе или другому. Спасибо за комментарий
solarplexus
19.11.2023 13:05Давайте возьмем определение заявки из текста. Заявка это коммит.
Теперь разберемся с вашими вопросами. Если вы ответите сами себе на те вопросы, что задали, подставив вместо заявки слово коммит, то всё встанет на свои места. И кому коммит, и кому повелительное наклонение, и т. д. и т. п.
И мне еще не понятно, откуда вы взяли, что практического применения в использовании в коммитак повелительного наклонения нет? Я открыл гитхаб, выбрал первые попавшиеся проекты, и вижу, что в комментах коммитов используются в imperative mood.
Я дико сомниваюсь, что вы не видите такую очевидную вещь. И я предполагаю, что вы о чем-то другом можете говорить.
ritorichesky_echpochmak
19.11.2023 13:05+1Мы уже много лет не отправляем патч почтой другому разработчику, чтобы он его применил к репозиторию. На этом "заявки" заканчиваются. А дальше я могу из своих коммитов автоматически нагенерить релизу changelog прям из github actions при вливании мержа в мастер или сверстать месячный отчёт для кастомера о выполненной работе. А вам для того, чтобы сделать то же самое, придётся каждый коммит переписать ручками. Вот вам два практических применения, теперь ваша очередь привести примеры практического применения imperative mood, чтобы все могли разобраться, почему стоит каждый раз мозг выворачивать прописывая "сделай" на заведомо выполненную работу. Не "дядечка в интернете или на курсах посоветовал", а вот практический кейс, который делает гит и историю, которую он хранит, ценнее
solarplexus
19.11.2023 13:05+2Ваш пример применим и используется только у вас. И переучивать вас никто не может. Вы заточили своюй рабочий процесс под себя. На мой взгляд, это прям круто.
Выше вам предоставили 4 ссылки о рекомендациях (сам git, соглашение о коммитах и т.д.) Они для вас не авторитет? А почему тогда ваша рекомендация должна быть авторитетной? Для нас вы "дядечка в интернете".
Я не встречал "сделай", если вы про наш язык. А вот, "fix", "add" и т. п. можете посмотреть, например в исходниках ядра линукса от Торвальдса (или и его проект для вас не авторитетен?). Вот, только там встречаются персонажи, которые не потрудились писать коммиты в одном рекомендованном стиле. Это не криминал, но выглядит как бардак. Вы всё еще против "Соглашения о коммитах"?
ritorichesky_echpochmak
19.11.2023 13:05Ссылки в первой из которых написано "мы сами так не делаем, но вы как мы не делайте". Если что, я читал эту классную книжку и там действительно много отличных примеров как можно сделать. Но далеко не все из них вам и вашей команде действительно нужны для того чтобы инструмент приносил пользу и им было одно удовольствие пользоваться, а не дополнительную когнитивную нагрузку и срачи в команде из-за того что кто-то опять придрался к формальностям, а ревью самого коммита, по сути, так и не сделал.
Не "не потрудились", а на автомате написали в естественной форме, потому что каждый раз нужно вспоминать какие-то неактуальные правила, оставшиеся там со времён царя гороха, а не писать в нативной форме как есть. И, как видите, линукс от этого не сломался. И не только линукс.
solarplexus
19.11.2023 13:05Только что заметил, что в conventionalcommits ни слова о повелительном наклонении, хотя в примерах используют. Может, это уже и есть стандарт?
И там есть абзац "Зачем использовать Соглашение о коммитах". Правда, это применимо, если вы приглашаете других разрабов или сами участвуете в чужих проектах. Как я сказал выше, к вам это не применимо, т.к. у вас свой настроенный и возможно изолированный проект.
ritorichesky_echpochmak
19.11.2023 13:05Давайте ссылку на RFC, если это "стандарт". Что же это за стандарт такой, если его можно не соблюдать регулярно даже в одних и тех же командах и нигде ничего не ломается.
Это в принципе так себе "применимо", не только ко мне, потому что не влияет ни на что, кроме настроения людей уверенных в том, что так должно быть. Ни на Git, ни на CI, ни на код ну никак не влияет. Вот за что действительно нужно компостировать мозг и бить по рукам, так это за коммиты вида "Fix", "Small fix", "hotfix", "sf" и прочую чепуху не несущую никакого смысла. Зато в той форме, в которой вы хотели, ага. Почему-то вот просто "Fixed" никто не коммитает - от этого коробит, потому что напрашивается текст что собственно пофикшено, а одно единственное слово "fix" - легко.
solarplexus
19.11.2023 13:05Какую ссылку? Утверждения же не было). Люди согласились разговаривать на одном языке. Вот и всё. А я топлю за порядок.
solarplexus
19.11.2023 13:05Патч не отправляем почтой. А общие правила оформления остались. Вы предлагаете изменить правила написания комментов? А надо ли?
ritorichesky_echpochmak
19.11.2023 13:05Если вы не отправляете патчи почтой, то уже что-то поменялось. Почему бы не поменять что-то ещё? Аргументация в духе "при диалапе так страдали и сегодня надо" - ну такое
solarplexus
19.11.2023 13:05Дистры линукса тоже имеют массу проблем с путями и повторяющимся функционалом программ (арч - исключение) тянущиеся со времён царя гороха. Почему-то все до сих пор страдают. Мне кажется, к коммитам не применяется слово страдание. На питоне никто не жалуется на обязательность табов - ты не напишешь по-другому "на автомате".
Для тех кто пока не умеет у себя в проекте писать правильно, существуют рекомендации. Да и в общих открытых проектах желательно придерживаться одного стиля, чтобы не было так:
ritorichesky_echpochmak
19.11.2023 13:05-1На питоне никто не жалуется на обязательность табов
Давайте я пожалуюсь: пробелы
По поводу практической стороны повелительного наклонения, в отличие от DRY, соблюдения путей и требований конкретного языка программирования, я так понимаю, у вас ничего не будет, только отговорки и несопоставимые примеры.
Приравнивать некоторые личные договорённости и рекомендации, да хоть и coding conventions, к стандартам - ну такое себе. Давайте тогда сразу ссылку на RFC?)
solarplexus
19.11.2023 13:05Обязательно нужна практическая сторона? На руби можно писать миллионами стилями, куча элиасов на одни и те же команды. Но, почему-то, народ тяготеет к одному стилю. Практика тут не причём.
solarplexus
19.11.2023 13:05Ну вот так. Такова жизнь. Кроме практической составляющей есть ряд и других составляющих, например, влияющие на эмоциональность.
Если я в кэмл-кейсе буду писать, когда принято в снейк-кейсе, практически как-то на полёт повлияет? А если я коммит буду оформлять без двоеточия после типа коммита, а тип коммита заключу в квадратные скобки:
<тип>: <Описание> [<тип>] <Описание>это как-то затронет весь ворк-флоу (парсерами коммитов можно пренебречь, в виду специфичности)?
Если что, я ваши сообщения не минусю. Моя оценка только в сообщениях.
ritorichesky_echpochmak
19.11.2023 13:05Мне кажется вы сами себя закапываете. Единый стиль кода в команде принимается именно потому что это практичнее - так код других участников проще воспринимать и сопровождать. Коммиты не нужно сопровождать и регулярно вдумчиво перечитывать. К коммитам основное требование - чтобы было понятно, что там в правках происходило. Если их вот прям парсят, тогда люди сами под свой парсер как-то должны адаптироваться и договориться, ну или свой парсер доработать, но это внутрикомандный вопрос, а не некий стандарт.
Не особо парюсь о минусах
baltic_tea
19.11.2023 13:05+1Есть конвенция о написании коммитов. Можно ее не придерживаться, но главное потом не жаловаться, что в вашей любимой библиотеке, которую вы вдруг захотели улучшить, ваш пул реквест даже не стали рассматривать на фоне оформленных "правильно" сотен других реквестов.
ritorichesky_echpochmak
19.11.2023 13:05Когда коммитаешь в чужой проект нужно придерживаться не рекомендаций которым гитовцы сами не всегда придерживаются, а соглашениям принятым в конкретном проекте.
D_E_S
19.11.2023 13:05+1Дополню исходя из опыта. В репозитории хорошо иметь не только README.md а ещё и License, Authors и важно Changelog. Все коммиты должны быть связанны с Changelog историей разработки поэтому каждый коммит должен начинатся с {code-task-tracker} а если мы делаем не монолит а микросервисы то мы должны иметь общий индекс системы чтобы понимать ещё и связи {index} и того чтобы понять что это лучше взять в квадратные скобках т.к. вот так git commit -m "[SHOP-ISSUE-994] feat: добавлен вывод строки" # index = shop, code-task-tracker = issue 994 т.к. так трекер не всегда может быть частью git. И нам остаётся только в Changelog указать что мы закрыли issue 994 для shop)))) и естественно описав что изменили.
История коммитов это очень хорошо. Главное не забывать что есть ещё теги, история изменений и правила ветвления. Всё в мести при правильном использования как раз и даёт полноту картины и удобства использования.
ritorichesky_echpochmak
19.11.2023 13:05только в Changelog указать что мы закрыли issue 994 для shop
Выглядит как вообще бесполезный changelog) Ну закрыли какую-то цифирь и что? Чем такой changelog лучше чем git log --oneline? Даже хуже, в логе хоть написано "добавлен вывод строки".
Tryd0g0lik
19.11.2023 13:05+1День добрый.
.gitignore - https://www.toptal.com/developers/gitignore/ - генератор
Git Command - https://gitexplorer.com/ - генератор синтаксиса
README - https://readme.so/ru - генератор
Не знаю на сколько актуальным будет, но может и пригодится.
abagnale
19.11.2023 13:05Как оформить README файл
И тут же идёт пример, где после заголовков (и перед ними!) нет пустых строк.
С комментариями (зачем), которые содержат в себе весь контент, который они комментируют.
Некоторые заголовки ещё и ссылки. Местами с нарушенным уровнем вложенности.
И для полной "красоты" далее идут "блоки" кода в одну строку.Не оформляйте так README, пацаны, на самом деле, не надо. (с)
Ilya00657
Вопрос по коммитам. По каким правилам, коммит должен быть в повелительном наклонении? Разве это не краткое изложение проделанной работы?
DrArgentum Автор
Вот, вот, вот и вот
Резюмируйте изменения в 50 символах или меньше Тут объясните их более детально, если необходимо. Выполняйте переносы строк примерно на 72 символах. В некоторых ситуациях первая строка комментания считается его заголовком, а все остальное - телом. Крайне важно отделять оделять одно от другого пустой строкой (если у сообщения вообще есть тело, конечно); различные инструменты типа `log`, `shortlog`и `rebase` не поймут вас, если заголовк и тело не будут отделены. Объясните здесь, какую проблему решает этот коммит. Уделите больше внимания тому, почему вы внесли эти изменения, а не тому, как именно вы это сделали (это объяснит за вас код). Есть ли сайд-эфффекты или другие неочевидные последствия у этих изменений? Если да, это нужно объяснить здесь. Параграфы разделяются пустыми строками. - Можно делать маркированные списки - Обычно в качестве маркера списка используется звездочка или тире с пробелом перед ними; но тут есть разные соглашения Если у вас есть баг-трекер [или система управления проектами], поместите ссылки на задачи в конце текста таким образом: Решено: #123 Смотрите также: #456, #789
sshikov
А почему правила, сформулированные синьором разработчиком из RedHat (ну или там еще кем-то) должны быть применимы к другим проектам, другим компаниям, и другим людям?
DrArgentum Автор
Признаю, ваша правда. Каждый может как угодно делать, но есть определенные правила. Я сам то и не использую повелительное наклонение... Спасибо за ваше мнение!
sshikov
Давайте называть вещи своими именами - это рекомендации, возможно от уважаемых и умных людей - но придерживаться их никто не обязан. Тем более если они не сформулировали ограничения на применимость своих рекомендаций (а я сколько видел таких советов - как правило ограничения никто не формулирует).
Ну т.е. к самим рекомендациям нет особых претензий - лучше коммиты оформленные по единому стандарту, чем какие попало. Вопрос скорее в соотношении трудозатрат на оформление, и профита, полученного в итоге. Я вот пришел к выводу, что кроме ссылки на jira, как правило больше ничего можно не писать - все равно через полгода эти тексты никому ничего не говорят, потому что они имеют смысл только в контексте, а в него еще надо попасть. Поэтому оставлять можно только то, что указывает на цель изменений - потому что сами изменения и так в коде и его истории остаются. А вот зачем сделали - это либо баг трекер, либо комментарии. И баг трекер лично мне удобнее.
Да скорее всего потому, что попробуйте сами себе объяснить, какую пользу вы получаете от его использования? А еще лучше - эту пользу измерить. И вряд ли у вас что-то путное намеряется (ну или как минимум - это сложно).
ritorichesky_echpochmak
А потом ваша команда спешно переезжает на другой багтрекер и история превращается в тыкву) Поэтому недостаточно только номер таски писать. И вообще заставлять людей лишний раз ходить в тормозную жиру, потому что лень было нормально 4-5 слов написать по мотивам заголовка в той же жире - ну такое себе.
sshikov
Ни разу в своей практике спешно не переезжал. И вообще переезжал один раз. С какой стати я должен о таком редком событии думать?
ritorichesky_echpochmak
По очень разным причинам. То что это не случалось лично с вами - вообще ни о чём не говорит. Ну точнее это говорит о том, что у вас нет некоторого опыта. У других есть. И это всё ещё никак не характеризует за что вы так ненавидите людей из команды, что заставляете их каждый раз переть в жирную жиру, открывать в браузере таску (которая ещё не факт что правильно оформлена) и гадать, насколько то что вы сделали соответствует этой таске.
ritorichesky_echpochmak
#123 Смотрите так же - это задача или где хотя бы какие-то знаки препинания? Почему их нельзя разнести на отдельные строки? Писать номер основной задачи в title, а не в конце текста - это отличная практика, добавочный текст коммита зачастую никто не смотрит.
По ссылкам можно найти как чувачки из гитбука противоречат сами себе
Это правила из их команды, потому что разработка гита ведётся сильно иначе, чем ваши личные проекты и тем более проекты компаний. Сообщество разработчиков Git - это вообще отдельный мирок со своей атмосферой и правилами. Сегодня, чтобы сделать Merge Request в Git, нужно не слабо так постараться, потому что нельзя просто взять акк на gmail и написать в рассылку, они всё ещё требуют plain text с вот тем самым форматированием по 50 и 72 символа. И именно этим обусловлена данная рекомендация к оформлению коммитов - их текстовыми письмами. 99% других разработчиков эти ограничения слабо касаются.
Sapfira_Al
По общепринятой конвенции коммиты на гите должны быть в повелительном наклонении. Нас сейчас учат не совсем так, как пишет автор, то есть указать первое основное слово и после него двоеточие - в первый раз вижу. Но за коммиты в неправильном оформлении (не в повелительном) существенно снимают баллы.