DEV Community

Discussion on: Changelog for developers?

Collapse
 
dmfay profile image
Dian Fay • Edited

Yeah, I see room for improvement in your example commit messages honestly:

"Refactor for tab issue fix": what fix? That could at least reference the commit number of the fix, or summarize it if that's possible without getting too verbose.

"Use calc to set width minus gutter": where? You answer this question in your changelog but it would be even better in the commit message. It's useful information no matter what.

The third is fine and your corresponding changelog entry is basically just changing the order of the words around. Overall, you're going to get tired of updating the same information in two places quickly, and you'll also likely find yourself hunting through one when the information you need is in the other. Making exceptions for certain "low-risk" commits is not something you can do consistently so it's guaranteed to let some useful information slip. Being more thorough with your commit messages (even better, using something like the conventional commit specification) will prevent the headaches of log duplication, and if you want a tidily organized summary there are tools like standard-version to generate them without the extra manual overhead.

Thread Thread
 
scottharrisondev profile image
Scott Harrison

All very good points,I think the reason the commit messages may seem vague is because we have the issue reference in each commit so 'refactor for tab issue' will be the tabs related to tsk020 which may be in JIRA as "change layout on gallery page to be responsive" or something, so the message is within that context, again probably a weak example. I think you're also right about not having the motivation to continue updating it, it may be fine for the devs we currently have for a while but as devs come and go and time goes on it will probably end up outdated. Hmmm

Thread Thread
 
jenbutondevto profile image
Jen

Is there a reason why it needs to be its own document? Especially if you're referencing stories/tasks in git messages.

If someone wants to read the reason why there was a commit they'd check the task which was tagged tsk020 in this case. Each of the changelog items "Gallery width now dynamic", "Menu button hidden on print" could be their own task, and the commits would be prepended with tsk021, tsk022 respectively. The branch would be named something like "feature/tsk020-change-layout-on-gallery-page".

Also when I'm opening a pull request I usually list out the changes. It's useful for yourself to see if you've filled the criteria of the story and also when someone is reviewing, they know what they're looking at and looking for. We delete branches after they are merged, but the PR doesn't go anywhere if anyone wants to go back and reference the changes.

Thread Thread
 
scottharrisondev profile image
Scott Harrison • Edited

The point of the changelog would be for when a developer comes back to a project after a while they can simply view the developer changelog as a way of saying 'what do I need to do and know to get my environment working and get up to speed'.

For example, "db now hosted on AWS" may be a part of the dev changelog but won't fit in to a git history. Now I know that if I need to access the DB I login to AWS rather than the previous service.

I agree that a task based changelog would be largely redundant, I think I'm still in the process of figuring out exactly what would be in the changelog to be honest but things like the example above would be super useful to store in one single place rather than the last dev to work on the proejcts mind. I think environment/third party services changes would be the main use for this file.