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

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

Я спробував googling "git changelog" і "git management changelog", але я не знайшов нічого, що б насправді говорило про робочий процес змін коду та про те, як це збігається з журналом змін. Зараз ми слідкуємо за процесом розвитку Рейна Генріха, і мені б дуже подобалося щось, що йшло разом із цим.

Чи є стандартний підхід, який мені не вистачає, чи це область, де кожен робить свою справу?

Дуже дякую за ваші коментарі / відповіді!

Це було близько 3-4 років тому, але заради майбутніх шукачів тепер можна генерувати чудові журнали за допомогою:

git log --oneline --decorate

Або, якщо ви хочете, щоб це було ще красивіше (з кольором для терміналу):

git log --oneline --decorate --color

Я зараз використовую у всіх своїх проектах переклад цього виходу на ChangeLog, це просто дивовижно.

Ви можете скористатися смаком журналу git, щоб допомогти вам:

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

Якщо ви добре називаєте свої гілки, так що злиття для ведучого відображається як щось на зразок "Об'єднана функція гілки-фобар", ви можете скоротити речі, лише показавши це повідомлення, а не всі маленькі зобов'язання, які ви об'єднали, які разом утворюють особливість:

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

і виконати це у своїй версії.

Якщо ваша проблема полягає в тому, що ці теми, що займаються фіксацією, не схожі на те, що ви хотіли б помістити в журнал змін, у вас майже є два варіанти: продовжуйте робити все вручну (і намагайтеся не відставати від цього регулярніше, а не грати в catch- на час випуску) або виправте стиль повідомлення про фіксацію. Один із варіантів, якщо суб'єкти не збираються робити це за вас, - це розмістити рядки типу "змінити: додано функцію foobar" в органи ваших повідомлень про фіксацію, щоб пізніше ви могли зробити щось на кшталт, git log --pretty=%B | grep ^change:щоб схопити лише тих супер -важливі біти повідомлень.

Я не зовсім впевнений, наскільки більше цього git може допомогти вам створити свої журнали змін. Можливо, я неправильно трактував, що ви маєте на увазі під "керувати"?

ВІДМОВА: Я є автором gitchangelog, про який я буду говорити далі.

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

Якщо ви хочете створити журнал змін зі своєї історії git, вам, мабуть, доведеться врахувати:

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

Опціонально вам може знадобитися певна категоризація (нові речі, зміни, виправлення) ...

Маючи на увазі все це, я створив і використовую gitchangelog . Це покликане використовувати конвенцію повідомлення про git вчинення для досягнення всіх попередніх цілей.

Конвенція повідомлення про фіксацію зобов’язана створити хороший журнал змін (з використанням або без використання gitchangelog).

зробити конвенцію повідомлення

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

Ви можете приблизно розділити свої зобов'язання на великі розділи:

• за наміром (наприклад: новий, виправити, змінити ...)
• за об'єктом (наприклад: doc, упаковка, код ...)
• за аудиторією (наприклад: розробник, тестер, користувачі ...)

Крім того, ви можете позначити деякі комісії:

• як "незначні" зобов'язання, які не повинні бути замінені у вашому журналі змін (косметичні зміни, невеликі друкарські помилки в коментарях ...)
• як "рефактор", якщо ви насправді не маєте жодних суттєвих змін. Таким чином, це також не повинно бути частиною журналу змін, що відображається, наприклад, кінцевому користувачеві, але може представляти певний інтерес, якщо у вас є журнал змін розробника.
• ви можете також позначити "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 

Тож якщо ви помітили, я вибрав формат:

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

Щоб побачити фактичний результат виводу, ви можете подивитися в кінці сторінки PyPI gitchangelog

Щоб побачити повну документацію моєї конвенції про повідомлення, ви можете переглянути довідковий файл gitchangelog.rc.reference

Як створити з цього вишуканий журнал змін

Тоді зробити повний журнал змін досить просто. Ви можете зробити свій власний сценарій досить швидко або використовувати gitchangelog.

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

Я впевнений , що ви знаєте , що є багато інших git logдля changelogінструментів там також.

Більше до зміну CHANGELOG. Скажи мені, якщо тобі це подобається.

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B

gitlog-to-changelogСценарій знадобиться для створення GNU-стилі ChangeLog.

Як показано на рисунку 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також записується у сховище, так що його можна редагувати (наприклад, для виправлення помилок друку) без зміни повідомлень про фіксацію.

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

git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Для проектів GitHub це може бути корисним: github-changelog-generator

Він генерує журнал змін із тегів закритих питань та об'єднаних запитів.

Цей CHANGELOG.md був створений цим сценарієм.

Приклад:

Журнал змін

1.2.5 (2015-01-15)

Повний журнал змін

Реалізовані вдосконалення:

• Використовуйте віху, щоб вказати, в якій версії виправлено помилку №22

Виправлені помилки:

• Помилка при спробі генерування журналу для репо без тегів №32

Об’єднані запити на потяг:

• Клас PrettyPrint включений із використанням малих літер 'pp' # 43 ( schwing )

• підтримка підприємства github за допомогою параметрів командного рядка № 42 ( glenlovett )

Я також зробив для цього бібліотеку. Це повністю настроюється з шаблоном вуса. Це може:

• Зберігати у файлі, як CHANGELOG.md .
• Будьте опубліковані в MediaWiki
• Або просто надрукуйте для STDOUT

Я також зробив:

• Gradle плагін
• Maven плагін
• Дженкінс плагін
• Плагін Bitbucket сервера
• Інструмент командного рядка

Детальніше про 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}}
"

Або в Дженкінсі:

git log --oneline --no-merges `git describe --abbrev=0 --tags`..HEAD | cut -c 9- | sort

Це те, що я люблю використовувати. Він отримує всі коміти з останнього тегу. cutпозбавляється від хеш-факту. Якщо ви використовуєте номери квитків на початку повідомлень про фіксацію, вони групуються sort. Сортування також допомагає , якщо ви префікс деяких коммітов з fix, typoі так далі

Я дозволяю серверу CI передавати наступне у файл, названий CHANGELOGдля кожного нового випуску, з датою, встановленою у імені випуску-файла:

>git log --graph --all --date=relative --pretty=format:"%x09 %ad %d %s (%aN)"

Для журналу змін стилів GNU я приготував цю функцію

gnuc() {
  {
    printf "$(date "+%Y-%m-%d")  John Doe  <john.doe@gmail.com>\n\n"
    git diff-tree --no-commit-id --name-only -r HEAD | sed 's/^/\t* /'
  } | tee /dev/tty | xsel -b
}

З цим:

• Періодично я зобов’язую свої зміни робити їх резервними копіями та перезавантажувати їх, перш ніж робити остаточне редагування у ChangeLog
• потім запустіть: gnuc

і тепер мій буфер обміну містить щось на кшталт:

2015-07-24  John Doe  <john.doe@gmail.com>

        * gdb/python/py-linetable.c (): .
        * gdb/python/py-symtab.c (): .

Тоді я використовую буфер обміну як вихідну точку для оновлення ChangeLog.

Це не ідеально (наприклад, файли повинні бути відносно їх шляху ChangeLog, так що python/py-symtab.c без того, gdb/як я буду редагувати gdb/ChangeLog), але це хороша відправна точка.

Більш просунуті сценарії:

• https://github.com/tromey/git-gnu-changelog від Tromey, обслуговуючого персоналу GDB
• GCC's contrib / mklog
• https://github.com/davidmalcolm/gcc-refactoring-scripts/blob/1fc7fe038bffbb2b48d0a7a300625639f01aefa1/generate-changelog.py

Я маю згоду з Tromey, хоча: дублювання даних git commit у ChangeLog марно.

Якщо ви збираєтеся скласти журнал змін, складіть це резюме того, що відбувається, можливо, як зазначено на веб-сайті http://keepachangelog.com/

На основі bithavoc , він перераховує last tagдо HEAD. Але я сподіваюся перелічити журнали між двома тегами.

// 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