Повідомлення Git Commit: 50/72 Форматування

Тім Попп у своєму блозі стверджує, що стиль повідомлення Git фіксує в http://www.tpope.net/node/106 .

Ось короткий підсумок того, що він рекомендує:

• Перший рядок - 50 символів або менше.
• Потім порожній рядок.
• Залишився текст має містити 72 символи.

Його публікація в блозі дає обґрунтування для цих рекомендацій (які я буду називати "форматуванням 50/72" для стислості):

• На практиці деякі інструменти розглядають перший рядок як тему, а другий абзац - як тіло (подібно до електронної пошти).
• git log не обробляє обгортку, тому важко читати, якщо рядки занадто довгі.
• git format-patch --stdout перетворює зобов’язання на електронну пошту - тому грати приємно, це допомагає, якщо ваші комісії вже добре завернуті.

Хотілося б додати, що я думаю, що Тім погодився б:

• Акт узагальнення вашого зобов’язання є хорошою практикою, властивою будь-якій системі контролю версій. Це допомагає іншим (або пізніше ви) швидше знаходити відповідні доручення.

Отже, у мене є кілька кутів мого запитання:

• Який фрагмент «лідерів думок» або «досвідчених користувачів» Git охоплює стиль форматування 50/72? Я запитую це тому, що десь нові користувачі не знають або не цікавляться практикою спільноти.
• Для тих, хто не використовує це форматування, чи є принципова причина використання іншого стилю форматування? (Зверніть увагу, що я шукаю аргумент по суті, а не "я ніколи про це не чув" або "Мені все одно".)
• Емпірично кажучи, який відсоток сховищ Git охоплює цей стиль? (У випадку, якщо хтось хоче зробити аналіз на сховищах GitHub… підказка, підказка.)

Моя думка тут - не рекомендувати стиль 50/72 або збивати інші стилі. (Щоб бути відкритим щодо цього, я віддаю перевагу цьому, але я відкритий для інших ідей.) Я просто хочу отримати обґрунтування того, чому людям подобаються чи виступають проти різних стилів повідомлення Git. (Сміливо пропонуйте бали, про які також не згадували.)

Щодо рядка "підсумок" (50 у вашій формулі), у документації на ядро ​​Linux зазначено :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

З цього приводу, схоже, що підтримуючі ядра дійсно намагаються тримати близько 50. Ось гістограма довжин рядків підсумків у журналі git для ядра:

( переглянути повнорозмірний )

Існує дефіцит комітетів, у яких підсумкові рядки довші (деякі набагато довші), ніж цей сюжет може містити, не роблячи цікаву частину схожою на один єдиний рядок. (Мабуть, є якась фантастична статистична техніка для включення цих даних сюди, але так добре… :-)

Якщо ви хочете переглянути необмежену довжину:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

або текстова гістограма:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Щодо "лідерів думок": Лінус наполегливо виступає за обертання рядків для повного повідомлення про виконання:

[…] Ми використовуємо стовпці з 72 символами для обговорення слів, за винятком цитованих матеріалів, що мають певний формат рядка.

Винятки стосуються, головним чином, "непрозового" тексту, тобто тексту, який не було набрано людиною для комісії - наприклад, повідомлення про помилки компілятора.

Поділ презентації та даних приводить сюди мої повідомлення про фіксацію.

Повідомлення про фіксацію не повинно бути чітко зафіксовано при будь-якому числі символів, а натомість перерви рядків повинні використовуватися для розділення думок, абзаців тощо як частини даних, а не для презентації. У цьому випадку "дані" - це повідомлення, яке ви намагаєтеся отримати, а "презентація" - це те, як бачить користувач.

Я використовую єдиний підсумковий рядок у верхній частині і намагаюся бути короткою, але я не обмежуюся довільним числом. Було б набагато краще, якби Git насправді запропонував спосіб зберігати підсумкові повідомлення як окрему сутність від повідомлення, але оскільки це не так, я не повинен зламати його, і я використовую розрив першого рядка як роздільник (на щастя, підтримка багатьох інструментів це засіб розбиття даних).

Для самого повідомлення нові рядки вказують щось значиме в даних. Один новий рядок вказує на початок / перерву в списку, а подвійний новий рядок вказує на нову думку / ідею.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Ось як виглядає у глядача, який м'яко загортає текст.

Це підсумковий рядок, спробуйте зробити його коротким і закінчити перервою рядка.

Це думка, можливо, пояснення того, що я зробив у читаному для людини форматі. Це може бути складним і довгим, що складається з декількох речень, які описують мою роботу у форматі есе. Не вирішувати зараз (у авторський час), як користувач буде споживати ці дані.

Два перерви у рядку розділяють ці дві думки. Користувач може читати це по телефону або на широкоекранному моніторі. Ви коли-небудь намагалися прочитати обгорнутий текст із 72 символів на пристрої, на якому відображається лише 60 символів? Це справді болісний досвід. Крім того, вступне речення цього абзацу (якщо припустити формат стилю есе) має бути введенням до абзацу, тому, якщо інструмент вибере, можливо, він не захоче автоматично перегорнути, і ви просто побачите початок кожного абзацу. Знову ж таки, саме інструмент для презентації не я (випадковий автор на певному етапі історії) намагатись змусити моє конкретне форматування внизу всіх інших.

Як приклад, ось список пунктів:
* Пункт 1.
* Пункт 2.
* Пункт 3.

Я підозрюю, що автор рекомендації Git počin повідомлення, яку ви пов’язали, ніколи не писав програмне забезпечення, яке раніше споживатиметься широким набором кінцевих користувачів на різних пристроях (тобто веб-сайті), оскільки в цей момент еволюція програмного забезпечення / обчислень загальновідомо, що зберігання ваших даних із жорстко кодованою інформацією про презентацію є поганою ідеєю, що стосується досвіду користувачів.

Я погоджуюся, що цікаво запропонувати певний стиль роботи. Однак, якщо у мене немає можливості встановити стиль, я зазвичай дотримуюся того, що зроблено для послідовності.

Ознайомтеся з командами Linux Kernel Commits, проектом, який запустився git, якщо вам подобається, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , вони не відповідають правилу 50/72. Перший рядок - 54 символи.

Я б сказав, що послідовність має значення. Створіть належні способи ідентифікації користувачів, які здійснили зобов’язання (ім’я користувача, ім’я користувача.пошта - особливо у внутрішніх мережах. Користувач @ OFFICE-1-PC-10293982811111 не є корисною адресою контакту). Залежно від проекту, зробіть відповідні деталі доступними у комітеті. Важко сказати, що це повинно бути; це можуть бути завдання, виконані в процесі розробки, а потім деталі того, що змінилося.

Я не вірю, що користувачі повинні використовувати git одним способом, оскільки певні інтерфейси git трактують коміти певними способами.

Зауважу, є й інші способи пошуку комітетів. Для початку git diffрозповім, що змінилося. Ви також можете робити такі речі, як git log --pretty=format:'%T %cN %ce'відформатувати параметри git log.

Чи дійсно максимальна рекомендована довжина заголовка 50?

Я вірив у це роками, але, як я щойно помітив, документація "git počin" фактично говорить

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Можна стверджувати, що "менше 50" може означати лише "не довше 49".