5

I was reading what is a changelog in keepachangelog.com and says that we shouldn't drop our git logs for the creationg of this file, but I see a lot of projects do it like the Angular framework repository, so I am wondering what is the recommended strategy for doing this, what kind of users are we aiming for or the special cases in which we would like to drop our git logs in this file instead of writing it down ourselves.

I want to point out that I am new to this type of workflow as the company I am currently working for never used a changelog and VCS and I am trying to organize better the projects we develop.

Otto Cheley
  • 163
  • Try this one you will not be disapointed: https://github.com/github-changelog-generator/github-changelog-generator –  Nov 01 '18 at 01:50

2 Answers2

15

A change log should tell end users why they should upgrade, not what changed in the code.

Stay focused on the features and bug fixes being delivered to the end users of your software, be they other programmers in the case of code libraries, to the customers of your business or non technical people.

Change logs like:

  • Added Comment.cs class file and data mapping
  • Fixed bug in main procedure
  • Fixed runtime cast exception

Tell end users nothing about why they would upgrade. They are fraught with technical jargon that nobody understands. It's good information for other developers, but end users won't value this information.

Change logs like:

  • Added comments feature to blog posts
  • Fixed issue #582 causing errors after logging in
  • Fixed issue #37 causing errors after double clicking the save button

Show the value of the upgrade, without diving into technical details. When noting that you fixed a defect, if possible link to the defect report itself.

The commit history of your project is probably littered with technical jargon — and that's OK! It's the commit history of the code. The intended audience is other engineers on your team, not end users.

Curate your change log manually.

Greg Burghardt
  • 37,083
-2

Generally, no-one cares about change logs and if they do, they probably want gory details of each commit or at least the id of the ticket they raised if its fixed.

Put ticket numbers + short descriptions in the branch name and roll up your merge commit comments into a change log.

If you are publishing a change log with a commerical product, get the marketing dept to clean up the real change log into one they think will sell more copies.

Ewan
  • 75,506