Types of changes moods

[ghost]

I would appreciate some hints how to write changelog entries, similar to The seven rules of a great Git commit message.

[RichardLitt]

I'm not sure what hints you are looking for, since the blog explains clearly what is good and what ain't.

It may not explain this clearly, or Jiri wouldn't have opened this issue. @qeef would you be able to clarify what kind of questions you have after reading it, which further writing may help with? :)

[ghost]

Kind of small and stupid thinks like:

1. Write only subject (because action is in heading) to change.
2. Write in past (contradiction to 1, no verb).
3. Make a whole sentence, start with capital (contradiction to 1).
4. Write to proper change group.
5. Sentence should make sense if concatenate heading and subject (contradiction to 3).

Definitely I am not a guy who should discuss about English grammar but I am curious.

[cdbennett]

This is a good question. There are so many different ways to write change log entries, and I think this is similar to issue tracker bug titles.

For example:
Possible change log entries include

### Fixed
- Fix bug that corrupted saved data files.
- Fix crash when Ctrl+G is pressed.

It seems somewhat redundant to start each item with "Fix ..." since they're already in a "Fixed" section.
Another option:

### Fixed
- Saving corrupted data files
- Crash when Ctrl+G pressed

The section titled says some things were fixed. The item itself states what the incorrect behavior was.

The git.git (Git project itself) release notes are a change log that is written in what seems to be a somewhat inconsistent and quirky way, but it could provide some fodder for discussion. From the Git 2.8.2 release notes:

Fixes since v2.8.1
------------------

 * The tests that involve running httpd leaked the system-wide
   configuration in /etc/gitconfig to the tested environment.

 * Fetching of history by naming a commit object name directly didn't
   work across remote-curl transport.

The above entries describe the incorrect, bug behavior in past tense.

But some other entries in the same change log "fixes" section describe the changes in either a present perfect tense of the change ("crash has been fixed") or in the present continuous tense of the new behavior ("startup_info data are now available to Git subcommands"), or even in an incomplete sentence form (noun only: "Build updates for MSVC"):

 * A small memory leak in an error codepath has been plugged in xdiff
   code.

 * The startup_info data, which records if we are working inside a
   repository (among other things), are now uniformly available to Git
   subcommand implementations, and Git avoids attempting to touch
   references when we are not in a repository.

 * Build updates for MSVC.

This is a good discussion to have, even if there is no answer everyone can agree on. At least we should seek consistency within each change log file, and consider the advantages and disadvantages of different ways of documenting a particular change.

[andreasvirkus]

Not sure if this should be a continuation of discussion under this issue or a separate issue, but I find it unclear when to create a Fixed section and when to keep Fix x doing y entries under Changed?

Even if you look at the example changelog of this repo, then at times the fixes are listed under Changed and then under Fixed with no real pattern to them. Is there some logic to it that I'm missing?

https://raw.githubusercontent.com/olivierlacan/keep-a-changelog/master/CHANGELOG.md

E.g. [1.0.0] lists 6 entries prefixed with Fix, yet [0.0.8] has both of them represented.

[ghost]

Well, my feeling is that the whole "Keep a Changelog" is more about Markdown format used (which I really like) than about "How to write a changelog".

This issue is about "How to write a changelog".

Not sure if this should be a continuation of discussion under this issue or a separate issue, but I find it unclear when to create a Fixed section and when to keep Fix x doing y entries under Changed?

And finally, your question from my point of view - I would keep all the bugs fixed under "Fixed" section and everything else changed under "Changed" section. Rule of thumb maybe something like "If Issue exists, put it under Fixed"

Even if you look at the example changelog of this repo, then at times the fixes are listed under Changed and then under Fixed with no real pattern to them. Is there some logic to it that I'm missing?

I would say that even the CHANGELOG.md of this repo is properly formatted, there is plenty of issues like you pointed out.