tag-guidelines.md

Tagging

Прототип на английском: tagging guide. Здесь и далее следует его вольное изложение и адаптация на русском.

В описании изменений настоятельно рекомендуется использовать метки (tags, теги). Это просто некий текст в квадратных скобках []. Смысл в том, чтобы можно было найти все относящиеся к этой метке изменения простым grep.

[.^] [readme] Reworded some lines.
[*] [lua/string/quote] Fixed forgotten case with backspace quoting.
[?+] [string-concatter] Added experimental garbage-collection heuristic.
[!*] [parsing-core] Debugged! (At least hope so.) Just want to mark this state...
[/] [string/from_file] renamed to [file/as_string].

Дайджест изменений

В начале сообщения может быть тег дайджеста изменений со спецсимволами. Каждый спецсимвол - опциональный флаг. То есть может быть упомянут не более чем единожды. Значение их следующее:

• Важность

  • . -- мелочь. Изменеие не оказывает практически никакого влияния, кроме эстетического
  • ! -- важно. Важное изменение, которое ломает/правит целые подсистемы функционала

• Цель

  • ? -- эксперимент. Изменение содержит идею, требующую дальнейшей проверки.
  • ^ -- улучшение. Это когда с внешней точки зрения ничего не поменялось, но внутри код стал быстрее/красивее.
  • * -- исправление ошибки. Это когда с внешней точки зрения код вдруг стал работать так, как и предполагается. То есть исправление, не изменяющее интерфейс ввода/вывода.

• Средства

  • + -- добавление. Что-то добавлено. Новая функция, новый файл, новая подсистема...

  • - -- что-то удалено насовсем. Обычно что-нибудь ненужное.

  • / -- что-то переименовано или перемещено. Например, изменено имя экспортируемой функции. Или в коде используется функция с другим именем. Или файл переименован-перемещён.

    То есть, исправление, возможно изменяющее интерфейс ввода-вывода, но не изменяющее функционал.

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

    Можно ещё использовать

    • > -- импорт. Если код был откуда-то взят. В сообщении указать откуда. Иначе использовать +.
    • < -- экспорт. Код был вынесен в какой-то другой проект. В сообщении указать куда. Иначе использовать -.

Тег имени

После дайджеста изменений можно поставить пробел и тег имени. В большинстве случаев достаточно имени файла (без расширения, если это не приводит к неоднозначности), но в крупных системах логичнее использовать метку подсистемы, например [cookie-parsing].

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

Примечания

• Основное назначение тегов - предоставить уровень с меньшей детализацей.

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

    • Не старайтесь использовать какой-либо символ дайджеста, только потому что это возможно. Оставляйте суть, детали пишите текстом.

• Синтаксисы дайджеста изменений и тегов имён независимы. Возможно, для имён более удобны хэштеги #text. Здесь данный вариант не предлагается из соображений принципа Оккама.

• Использование такого рода меток облегчает написание patch notes и интерактивный rebase. В частности, однострочные сообщения можно отсортировать.