Хорошие способы управлять журналом изменений, используя git? - PullRequest
Новая
       27

Хорошие способы управлять журналом изменений, используя git?

191 голосов
/ 19 августа 2010

Я уже некоторое время использую Git и недавно начал использовать его для маркировки своих выпусков, чтобы мне было легче отслеживать изменения и видеть, какая версия работает у каждого из наших клиентов (к сожалению, В настоящее время код требует, чтобы у каждого клиента была своя собственная копия сайта PHP; я изменяю это, но это медленно).

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

Я пытался погуглить "git changelog" и "git manage changelog", но я не нашел ничего, что действительно говорило бы о процессе изменения кода и о том, как это совпадает с журналом изменений. В настоящее время мы следим за процессом разработки Рейна Хенрихса , и я хотел бы что-то, что согласилось с этим.

Есть ли стандартный подход, который мне не хватает, или это область, где каждый занимается своим делом?

Большое спасибо за ваши комментарии / ответы!

Ответы [ 12 ]

158 голосов
/ 19 марта 2014

Это было около 3-4 лет назад, но ради будущих искателей теперь возможно создавать великолепные журналы с: 

git log --oneline --decorate

Или, если вы хотите, чтобы это было еще красивее (с цветом длятерминал): 

git log --oneline --decorate --color

Передача этого вывода в ChangeLog - это то, что я сейчас использую во всех своих проектах, это просто потрясающе.

55 голосов
/ 20 августа 2010

Вы можете использовать некоторую разновидность git log, чтобы помочь вам: 

git log --pretty=%s                 # only print the subject

Если вы правильно называете свои ветки, так что слияние с мастером отображается как что-то вроде "Объединенная ветвь feature-foobar"Вы можете сократить количество вещей, только показывая это сообщение, а не все маленькие коммиты, которые вы слили, которые вместе образуют функцию: 

git log --pretty=%s --first-parent  # only follow first parent of merges

Вы можете дополнить это своим собственным сценарием,которые могут делать такие вещи, как удаление битов «Объединенной ветви», нормализация форматирования и т. д. В какой-то момент вы, конечно, должны написать это сами, конечно.

Затем вы можете создать новый раздел для журнала изменений один раздля каждой версии: 

git log [opts] vX.X.X..vX.X.Y | helper-script > changelogs/X.X.Y

и зафиксируйте это в вашем коммите релиза версии.

Если ваша проблема в том, что эти темы фиксации не похожи на те, которые вы хотели бы поместить в журнал измененийу вас есть два варианта: продолжать делать все вручную (и стараться не отставать от него более регулярно, вместо того, чтобы играть в догонялки во время релиза), или исправить своестиль сообщенияОдин из вариантов, если субъекты не собираются делать это за вас, заключался бы в размещении строк типа «изменить: добавленная функция foobar» в теле ваших сообщений о коммите, чтобы позже вы могли сделать что-то вроде git log --pretty=%B | grep ^change:, чтобы получитьтолько эти супер-важные фрагменты сообщений.

Я не совсем уверен, насколько больше, чем этот мерзавец может реально помочь вам создать журналы изменений.Может быть, я неверно истолковал, что вы подразумеваете под «управлять»?

51 голосов
/ 14 апреля 2014

ОТКАЗ ОТ ОТВЕТСТВЕННОСТИ: Я автор gitchangelog , о котором я буду говорить в следующем.

TL; DR: Возможно, вы захотите проверить собственный журнал изменений gitchangelog или вывод ascii , сгенерировавший предыдущий.

Если вы хотите сгенерировать журнал изменений из вашей истории git, вам, вероятно, придется рассмотреть:

  • выходной формат .(Чистый пользовательский ASCII, тип журнала изменений Debian, Markdow, ReST ...)
  • некоторые фильтрация коммитов (вы, вероятно, не хотите, чтобы все опечатки или косметические изменения попадали в ваш журнал изменений)
  • некоторые передают текстовый спор перед включением в список изменений.(Обеспечение нормализации сообщений, в которых есть заглавная буква из первой буквы или последняя точка, но это также может привести к удалению некоторой специальной разметки в сводке)
  • совместима ли ваша история git ?.Слияние, тегирование не всегда так легко поддерживается большинством инструментов.Это зависит от того, как вы управляете своей историей.

По желанию вам может потребоваться некоторая категоризация (новые вещи, изменения, исправления) ...

Учитывая все это, я создал ииспользуйте gitchangelog .Он предназначен для использования соглашения о коммитах git для достижения всех предыдущих целей.

Наличие соглашения о коммитах обязательно для создания хорошего списка изменений (с использованием или без использования gitchangelog).

соглашение о коммитах

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

Возможно, вы захотитеразделите примерно ваши коммиты на большие секции:

  • по назначению (например: new, fix, change ...)
  • по объекту (например: doc, package, code...)
  • по аудитории (например: dev, tester, users ...)

Кроме того, вы можете пометить некоторые коммиты:

  • как «второстепенные» коммиты, которые не должны быть отражены в вашем списке изменений (косметические изменения, небольшая опечатка в комментариях ...)
  • как «рефакторинг», если у вас нет каких-либо существенных изменений функций.Таким образом, это также не должно быть частью журнала изменений, отображаемого конечным пользователем, например, но может представлять интерес, если у вас есть журнал изменений разработчика.
  • вы также можете пометить «api», чтобы пометить изменения API или новыеAPI-интерфейс ...
  • ... и т. Д. *

Попробуйте написать свое сообщение о фиксации, ориентируясь на пользователей (функции) как можно чаще.

пример

Это стандартный git log --oneline, чтобы показать, как эта информация может храниться: * 

* 5a39f73 fix: encoding issues with non-ascii chars.
* a60d77a new: pkg: added ``.travis.yml`` for automated tests. 
* 57129ba new: much greater performance on big repository by issuing only one shell command for all the commits. (fixes #7)
* 6b4b267 chg: dev: refactored out the formatting characters from GIT.
* 197b069 new: dev: reverse ``natural`` order to get reverse chronological order by default. !refactor 
* 6b891bc new: add utf-8 encoding declaration !minor

Так что, если вы заметили, формат, который я выбралis: 

{new|chg|fix}: [{dev|pkg}:] COMMIT_MESSAGE [!{minor|refactor} ... ]

Чтобы увидеть реальный результат вывода, вы можете посмотреть на конец страницы PyPI gitchangelog

Чтобы увидеть полную документацию моего коммитаСоглашение о сообщениях вы можете увидеть в справочном файле gitchangelog.rc.reference

Как создать из этого

* 1098 изысканный журнал изменений. Тогда довольно простосделать полный список изменений.Вы можете довольно быстро создать свой собственный скрипт или использовать gitchangelog.

gitchangelog, чтобы сгенерировать полный журнал изменений (с поддержкой секционирования как New, Fix ...), и его можно настроитьк вашим собственным обязательствам.Он поддерживает любой тип вывода благодаря шаблонам через Mustache, Mako templating и имеет устаревший движок по умолчанию, написанный на raw python;все 3 современных движка имеют примеры того, как их использовать, и могут выводить журнал изменений, как тот, который отображается на странице PyPI в gitchangelog.

Я уверен, что вы знаете, что существует множество других git log - changelog инструменты там тоже.

24 голосов
/ 28 ноября 2011

Еще к вопросу CHANGELOG.Скажи мне, если тебе нравится это. 

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B
22 голосов
/ 24 мая 2013

Сценарий gitlog-to-changelog пригодится для создания ChangeLog.

в стиле GNU. Как показано gitlog-to-changelog --help, вы можете выбрать коммиты, используемые для генерации ChangeLog файл, используя либо параметр --since: 

gitlog-to-changelog --since=2008-01-01 > ChangeLog

, либо передав дополнительные аргументы после --, которые будут переданы в git-log (вызывается внутренне gitlog-to-changelog): 

gitlog-to-changelog -- -n 5 foo > last-5-commits-to-branch-foo

Например, я использую следующее правило на верхнем уровне Makefile.am одного из моих проектов: 

.PHONY: update-ChangeLog
update-ChangeLog:
    if test -d $(srcdir)/.git; then                         \
       $(srcdir)/build-aux/gitlog-to-changelog              \
          --format='%s%n%n%b%n' --no-cluster                \
          --strip-tab --strip-cherry-pick                   \
          -- $$(cat $(srcdir)/.last-cl-gen)..               \
        >ChangeLog.tmp                                      \
      && git rev-list -n 1 HEAD >.last-cl-gen.tmp           \
      && (echo; cat $(srcdir)/ChangeLog) >>ChangeLog.tmp    \
      && mv -f ChangeLog.tmp $(srcdir)/ChangeLog            \
      && mv -f .last-cl-gen.tmp $(srcdir)/.last-cl-gen      \
      && rm -f ChangeLog.tmp;                               \
    fi

EXTRA_DIST += .last-cl-gen

Это правило используется во время выпуска для обновления ChangeLogс последними еще не записанными сообщениями о коммите.Файл .last-cl-gen содержит идентификатор SHA1 последнего коммита, записанного в ChangeLog, и хранится в репозитории Git.ChangeLog также записывается в хранилище, так что его можно редактировать (например, для исправления опечаток) без изменения сообщений фиксации.

17 голосов
/ 19 сентября 2012

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

git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B
13 голосов
/ 07 ноября 2014

Для GitHub проектов это может быть полезно: github-changelog-generator

Он генерирует список изменений из тегов закрытых вопросов и объединяет ихpull-запросы.

Этот CHANGELOG.md был создан с помощью этого сценария.

Пример:

История изменений

1.2.5 (2015-01-15)

Полный список изменений

Реализованные улучшения:

  • Используйте веху, чтобы указать, в какой версии исправлена ​​ошибка # 22 * ​​1036 *

Исправлены ошибки:

  • Ошибка при попытке создать журнал для репо без тегов # 32

Объединенные пул-запросы:

  • Класс PrettyPrint включен с использованием строчной буквы 'pp' # 43 ( schwing )

  • поддержка корпоративного github с помощью параметров командной строки # 42 ( glenlovett )

10 голосов
/ 08 декабря 2015

Я также сделал библиотеку для этого.Это полностью настраивается с шаблоном Усы.Это может:

  • Храниться в файле, например CHANGELOG.md .
  • Публиковаться на MediaWiki
  • Или просто напечатать в STDOUT

Я также сделал:

Подробнее о Github: https://github.com/tomasbjerre/git-changelog-lib

Из командной строки: 

npx git-changelog-command-line -std -tec "
# Changelog

Changelog for {{ownerName}} {{repoName}}.

{{#tags}}
## {{name}}
 {{#issues}}
  {{#hasIssue}}
   {{#hasLink}}
### {{name}} [{{issue}}]({{link}}) {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
   {{^hasLink}}
### {{name}} {{issue}} {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
  {{/hasIssue}}
  {{^hasIssue}}
### {{name}}
  {{/hasIssue}}

  {{#commits}}
**{{{messageTitle}}}**

{{#messageBodyItems}}
 * {{.}} 
{{/messageBodyItems}}

[{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*

  {{/commits}}

 {{/issues}}
{{/tags}}
"

Или в Jenkins:

enter image description here

3 голосов
/ 08 декабря 2015 
git log --oneline --no-merges `git describe --abbrev=0 --tags`..HEAD | cut -c 9- | sort

Это то, что я люблю использовать.Он получает все коммиты с момента последнего тега.cut избавляется от хеша коммита.Если вы используете номера тикетов в начале ваших сообщений о коммите, они группируются с sort.Сортировка также помогает, если вы используете префикс определенных коммитов fix, typo и т. Д.

2 голосов
/ 12 июля 2016

На основе bithavoc , в нем перечислены last tag до HEAD.Но я надеюсь перечислить журналы между 2 тегами. 

// 2 or 3 dots between `YOUR_LAST_VERSION_TAG` and `HEAD`
git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Список журналов между 2 тегами. 

// 2 or 3 dots between 2 tags
git log FROM_TAG...TO_TAG

Например, он будет перечислять журналы от v1.0.0 до v1.0.1. 

git log v1.0.0...v1.0.1 --oneline --decorate
Страница:
...