commit message titles and changelog entries

[Jan Mulder]

On 02-02-18 22:59, Lubomir I. Ivanov wrote:
> hello,
> 
> 1)
> 
> this suggestion is triggered by the need for streamlining the addition
> of changelog entries by contributors in the CHANGELOG.md file.
> 
> right now, we merge PRs that make an important change, but such PRs do
> not append a change in the CHANGELOG.md file. adding notes in
> CHANGELOG.md has to be made a requirement in PRs, otherwise before a
> release one has to go over the usually big list of commits and find
> relevant missing entries.

Historically, we have pretty concise changelogs, more or less hand made, 
and relatively high level. Like "Numerous spelling errors", "Lots of 
small UI fixes". Obviously, this does tell only a part of the story, and 
possible relevant change can be forgotten in this process. So this does 
not seem the way to go.

However, the big question is here: for who do we write the changelog? 
When it is for the website and announcements on internet, I tend to 
prefer the short and concise high level like we had, instead of a long 
list that seems correct and detailed enough (for who?).

For example: in the PR 1091 one item is "Cloud-storage: support 
non-https:// repositories for saving" ... yes I know where this is 
coming from ... but the general public?

> 
> by doing that we also need a standardized CHANGELOG.md entry format.
> 
> my suggestion is the following:
>      - Area: change that was made (#github-link)
> 
> examples:
> - Planner: fixed a bug when moving data points (#32132)
> - Mobile: fixed a bug when clicking button X. The bug also affected
>    menu X (#32132)
> 
> notes about the format:
> - the area name is uppercase
> - lowecase after the "Area: ", should it be uppercase here?
> - no period at the end of an entry only in-between sentences
> - when there is a related issue a (#github-link) has to be added at the end
> - first line stats with "- " and no indentation. the next lines are
> indented by "  ".
> 
> example areas:
> - Planner
> - Mobile
> - Desktop
> - Bluetooth
> - Map-widget
> - Cloud-storage
> - Uemis
> - Import
> - Export
> - Profile
> - Libdivecomputer
> 
> opinions about this?

Nice, but a little too detailed to my liking. Are you thinking of some 
automation/tooling behind it to check for these rules?

> 
> 2)
> 
> for commit messages-  until now we have accepted commit messages that
> do not specify an area, like these:
>     Fix bug when clicking button X
>     Small whitespace fix

Fine for me. When I want to look at a commit, I do not only read the 
title, but also the rest of the text and even the code change if needed.

In practice, it is often difficult to exactly pinpoint the area (and 
being concise). For example (from the PR 1091), "Bluetooth: do not add 
duplicate BT/BLE items", this mobile only, and it is even not 
(technically) restricted to Bluetooth. And the originating commit says 
"connectionList" and the related issue #1069 even says "mobile: During 
DC import, Rescan duplicates connections".

> 
> these are kind of vague, thus i would suggest requiring (perhaps not
> strictly) an area prefix or a filename, like so:
>     Divelist: Fix bug when clicking button X
>     divelist.cpp: fix whitespace
> 
> any opinions about this too?

In general: ok. But I come back to my earlier remark: for who do we 
write the changelog?

--jan