4

Before I start the question I want to tell you guys I'm new to this type of workflow. The previous companies I worked didn't used Version Control and/or changelogs. Also, I've been working as freelancer for sometime, so never felt the necessity to do so. But now I'm trying to have a better organization of my projects and I'm trying to use changelogs and Version control.

I was also reading other questions here and I understood the purpose of a version control, changelog, semantic version (which is the version type I'll be using), currently I'm using SourceTree (locally), I also understood the concept for each commit, branch, etc...

What I don't understand very well is how to integrate the Version control (commits) with a detailed changelog. What should go into the changelog? How often should I update it? How should it be segmented?

For example, if I'll update the changelog for each commit, it can be very extensive, but it's also important to have detailed information about the progress on the project.

Since the third number is related to bug fixes, instead of features, should I segment the changelog based on the feature version number? For example:

# 1.2.0
- Description of this version.
- Fixes
    + 1.2.1 - This is the fix number 01
    + 1.2.2 - This is the fix number 02
    + 1.2.3 - This is the fix number 03
    + 1.2.4 - This is the fix number 04
# 1.1.0
- Description of this version.
- Fixes
    + 1.1.1 - This is the fix number 01
    + 1.1.2 - This is the fix number 02
    + 1.1.3 - This is the fix number 03
    + 1.1.4 - This is the fix number 04

Or what other considerations do i need to have when adopting this type of workflow? Keep in mind I'm new to this scenario, so every type of information for me would be very appreciated!

7

Commit messages in a version control repository have a different audience than change logs.

The point of version control is to track the evolution of a code base so that you can later understand why something was changed, and so that you can revert changes if they are problematic. This is like a “save point” in a video game: if you mess up something, you can simply go back. Additionally, a VCS allows multiple developers to cooperate on a project, without accidentally overwriting each other's changes.

For these reasons, the audience of VCS commit messages is other developers, or your future self. Commit message will often be quite short (“implement Foo-Bar feature”, “reformat code”), but some commits may also contains extensive explanations of these changes. In my experience, commit messages for design changes or bugfixes benefit from a more in-depth explanation.

In contrast, change logs are for users. A change log is marketing to new users, and assists existing users when they update. The change log should point out new features, fixed bugs, or changed behaviour of your software. Any change should be mentioned here that would, taken on its own, increment your version number. Internal changes that don't change user-visible behaviour should not be mentioned in the change log, even though they do deserve their own commit.

There are also differences when you commit or write the change log:

You should commit whenever you've completed a self-contained action (like implementing a small feature), and commit separate changes separately. E.g. if you want to implement some new feature but need to change your design first, you should have one commit for the design change, and then another commit for the actual feature – keeping commits fairly small and cohesive makes it easier to understand them later. Additionally, you should commit whenever you've made something you wouldn't want to lose. Depending on personal style, this may result in multiple commits per hour (esp. when making many small unrelated improvements) or in a commit every few days (e.g. for experimental work where you aren't sure where you are going). In any case, every commit should represent a known-good, working state of your application – test before you commit!

A change log is usually written as part of a release process. Before you make your new version available, you review any changes that made it into this release, then explain them to users. This often does involve going through your VCS history to see what changed, but many commits are not relevant to users, and nearly everything will have to be phrased differently so that it makes sense to users. You can't generate a change log automatically from the VCS history.

  • A couple of years ago, I had this idea of using merge commits of feature branches for changelogs. I never tried it, though. It would require you to not use fast-forwards for feature merges. That way, you could generate a changelog from the history automatically, and even correctly annotate it with versions, assuming you tag appropriately. Similarly, I thought about putting release notes in annotated tags, again making it possible to automatically generate releases directly using nothing but source files and VCS metadata. – Jörg W Mittag Apr 10 '17 at 17:20
  • 1
    @JörgWMittag putting release notes into tags actually seems like a good idea, thanks! However, I merely wanted to discourage a “I know, I'll do git log >>Changes.txt” approach to generating the changelog, which tends to be useless for users if only done as an afterthought. – amon Apr 10 '17 at 17:27
  • Yeah. Linux and Git itself use git shortlog (or git log --pretty or similar) for changelogs, but that's a special situation since the "users" of Linux changelogs are distro kernel developers, and the users of Git changelogs are users of Git, who are of course developers themselves. And, of course, the Linux and Git developers know that and write their commit messages accordingly. In general, it works for stuff like web services, frameworks and libraries, where the target audience are themselves developers, but not for user-facing stuff like apps, desktop, mobile, or web. – Jörg W Mittag Apr 10 '17 at 17:29
  • That's a nice point of view! It made things a lot more clear to me. This is all new and still kind of confusing, so this was very helpful. Do you have any other content you'd recomend so i can study it more? – celsomtrindade Apr 10 '17 at 22:56
  • 1
    I really like Keep a Changelog as a reference. – eidsonator Apr 11 '17 at 20:34

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.