Пять полезных советов при составлении коммит сообщения

Original author: Caleb Thompson
  • Translation
image
Итак, Вы готовы сделать свой великолепный коммит, который, безусловно, делает код чуточку лучше, либо фиксить какой-то баг, а может, Вы и вовсе решили поменять переходы строк на Windows/Unix-Style? Естественно, Ваш код безупречен и достоин всевозможных похвал! Браво! Достойно ли Ваше сообщение Ваших трудов? Смогут ли потомки разобрать, что Вы сделали через месяц? Через год? Десять лет?



  1. Первая строка должна составлять 50 символов или меньше и завершаться пустой строкой (\n\n). Для редактора Vim существует множество плагинов для синтаксиса, авто-отступов и по типу файлов, которые могут очень легко помочь в этом.

  2. Добавьте эту строчку в свой файл .vimrc для проверки орфографии, а также авто-перехода строки в рекомендуемые 72 символа:
    autocmd Filetype gitcommit setlocal spell textwidth=72

  3. Никогда не используйте флаги для сообщения -m / --message=
    Это ставит вас в рамки для описания внесенных изменений, вам приходится умещать своё сообщение в маленькую строчку, и это мало похоже на целую страницу в истории вашего кода:
    git commit -m "Fix login bug"

    Более полезное и информативное сообщение может выглядеть так:
    Перенаправление пользователя после авторизации

    chyrius.com/path/to/relevant/card

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

    * Сохранение пути в переменной сессии
    * Перенаправление на сохраненный путь после удачной авторизации




    Ответьте на несколько вопросов:
    1. Почему данное изменение необходимо?
      Этот вопрос расскажет вашим потенциальным pull request ревьюверам, что именно в коммите, позволит им проще распознать несвязные изменения.
    2. Как коммит решит проблему?
      Опишите простым языком ваши изменения:
      «Реализовано красное-черное дерево для увеличения скорости поиска» или «Удален пакет зависимости <такой то>, который вызывал проблему <описание проблемы>».
      Если ваши изменения очевидны, то этот вопрос не обязателен.
    3. Вызывают ли изменения побочные эффекты?
      Пожалуй, один из самых важных вопросов, он может указать на проблему множества изменений в одном коммите или ветке. Одно или два связных изменения в коммите, это нормально, но если их 5 или 6, это означает ваш коммит делает слишком много :(

      Вы со своей командой должны заранее договориться, сколько изменений максимально умещается в один коммит/ветку.




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


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

    Отдельное спасибо Tim Pope, который попытался установить новый стандарт для коммит сообщений.

    Дополнительное спасибо создателю Git и убежденному стороннику хороших коммит сообщений, Linus Torvalds.
Share post

Similar posts

AdBlock has stolen the banner, but banners are not teeth — they will be back

More
Ads

Comments 16

    0
    мне кажется или что-то было прям переведено гуглом.

    Субъективно — тяжело читается. например вот это:
    > Пользователь перенаправляется на домашнюю страницу после авторизации,
    > что отличается от оригинальной запрошенной страницы до авторизационной
    > формы, это создает некоторое неудобство пользования.
      +1
      Предложите автору свой вариант. Как по мне — вполне себе связное и подходящее для ситуации сообщение.
        –1
        Предлагаю:

        Линус Торвальдс теперь верстает сайты для молодых мам.
          0
          Как минимум не английский порядок слов:
          Если вы употребляете в своём лексиконе:«авторизационная форма», то вы как минимум странный!)

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

        +7
        Я так понимаю, что это привет от невозможности связать коммит с породившей его задачей?
          +10
          Никогда не используйте флаги для сообщения -m / --message

          Данные флаги позволяют создавать многострочное описание коммита. Если не закрывать строку, то можно добавлять переносы нажатием на Enter.

          image
            +1
            Я понял так, что автор имел ввиду, это чисто психологический аспект, чаще всего мы делаем коммит с консоли, используя -m "" и не вдумываемся в содержание, сделал и забыл, Caleb Thompson упирает на то, что бы каждый коммит имел смысл.
              –1
              А надо вдумываться везде.
                0
                Либо Windows…
                –1
                Практически всегда использую только однострочные комментарии при комите + номер тикета.
                Т.е. в этом случае — что-то вроде "#NNNN After login, redirect customer to requested page instead of home page".
                Это позволяет просматривать историю более компактно и избавляет от многострочных комитов, которые выглядят как
                "#NNNN fixed redirect issue \n (много текста по сути изменения)".

                А такое длинное описание — ему место в тикете (описание проблемы) + комментарии в коде.
                +8
                Как показала практика, проще всего подобрать описание в одну строчку, тогда легче найти что-то по истории.
                  –2
                  SEO добралось до Git'а?
                    +2
                    Ага
                    +4
                    Являюсь сторонником грамотно написанных сообщений к коммитам, но некоторые советы написанные в статье — это через чур, по крайней мере для моего workflow.
                    autocmd Filetype gitcommit setlocal spell textwidth=72 и Никогда не используйте флаги для сообщения -m
                    Достаточно спорные советы — если вы правильно пользуетесь гитом и у вас частые атомарные коммиты, то вы будете повторяться в сообщениях к каждому коммиту, просто для того чтобы обойти ограничение.
                    Покажу на примере — мне нужно сделать модальное окно для авторизации. Что делаем сначала? Правильно, создаем новую ветку в названии которой уже можно проследить, для чего она создана, к примеру — feature-authorization-on-modal-windows. Потом делаем частые маленькие коммиты, описывающие зачем мы это сделали (специально посмотрел сейчас log — в основном коммиты по 50-70 символов). Когда задача сделана и протестирована, вливаем ее в qa или основную ветку, а вот тут, в merge коммите и можем описать все что написано в 4 пункте и зачем, и почему именно так, и какие проблемы могут возникнуть.

                    В общем к чему это я — не копируйте слепо, то что вам советуют, применяйте к своему рабочему процессу. Ну и, конечно, пишите грамотные сообщения к коммитам, всегда думайте, а можно ли определить по этому сообщению, что именно я сделал, без использования diff.
                      +3
                      Еще дополнение по поводу пункта 5:
                      Во многих проектах, таких как github, gitlab, redmine и прочих, можно прямо в сообщениях к коммиту делать ссылки на соответствующие issue, к примеру «Resolve bug with ugly modal window in IE9 #123» станет ссылкой на issue 123 в веб-интерфейсе. Можно даже управлять issue при помощи определенных слов, к пример «Resolve bug with ugly modal window in IE9,fix #123» автоматически закроет этот тикет.
                        +4
                        пользуйтесь багтрекером и вставляйте номер тикета в сообщение коммита (если он в default) или именуйте бранчипо номеру тикета (если бранч). тогда в коммите достаточно сказать «добавил тестов» или «поправил баг с авторизацией» а не писать простыни — IMHO это большооой overkill.

                        Only users with full accounts can post comments. Log in, please.