commit message titles and changelog entries

Lubomir I. Ivanov neolit123 at gmail.com
Sat Feb 3 01:30:39 PST 2018


On 3 February 2018 at 10:33, Jan Mulder <jlmulder at xs4all.nl> wrote:
> 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?
>

i draw my experience (i.e. "where i've seen this") from a certain
closed source software for audio engineers with an open-sourced
backend and a fairly large and technical user base, where the users
demand details from the updates.

these developers follow the "release-small-release-often" model and
their change logs look like this:
    # Regions: ensure time signature remains consistent at start/end
of moved regions [p=1918885]
or:
    <Area>: <details about the change> [reference thread / issue]

full log: https://forum.cockos.com/showpost.php?p=1919544&postcount=1

i find this changelog useful for both developers and the wider public.
if the users have questions about a certain vague entry, they have the
means to ask us.

>
>>
>> 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?

i think automating would just add another level of complication for
us. the maintainer merging the PRs should just proof read the change
log entries.
as long as they follow the consistent styling it would be OK for
certain entries to come up with custom areas / prefixes, even.

one convenient feature of Github is that it allows us to push commits
on top of user PR branches to possibly add a commit touching the
changelog..

>
>>
>> 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".
>

i guess that's true. i have followed this scheme for a long time for
my commits here and i try to always prefix a commit with "something: "
even if it's hard to come up with something.

>>
>> 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?
>

lubomir
--


More information about the subsurface mailing list