commit message titles and changelog entries

Lubomir I. Ivanov neolit123 at gmail.com
Sat Feb 3 10:41:16 PST 2018


On 3 February 2018 at 17:41, Dirk Hohndel <dirk at hohndel.org> wrote:
>
>> On Feb 3, 2018, at 2:29 AM, Jan Mulder <jlmulder at xs4all.nl> wrote:
>>
>> On 03-02-18 10:30, Lubomir I. Ivanov wrote:
>>> 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.
>>
>> Ok, looked at this, and this changelog is basically seems the output of git log. Useful for developers? No, they already have the tools for this. So while useful, it does does not add anything *new* for developers. Useful for users ... well I cannot speak for all users, but it would surprise me when the average Subsurface is really interested in git log style output.
>
> I don't think this level of details is useful for the typical user.

perhaps the bigger issue is that everyone adding changelog entries
uses a different style.
waiting on proposals from the the mailing list on how to standardize
the style for these a little.

>
>>> 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.
>>
>> So ... the maintainer merging patching up the missing changelog stuff ... well ... that seems like babysitting to me. I would just review with: NAK, changelog missing/wrong.
>
> It's a fine line. I don't want to make it too hard to contribute, but yes, in general requesting that the author adds a CHANGELOG entry seems fair.
>
>>>> In general: ok. But I come back to my earlier remark: for who do we write
>>>> the changelog?
>>
>> But what is missing in the discussion now, is an answer to this question. This answer cannot be a simple: for all users and developers and the website and Facebook announcements (as I do not believe that there is a unified list that suits all at the same time).
>
> I want to be able to copy from the ReleaseNotes (which are the target for the CHANGELOG file, which exists to have fewer merge conflicts) to the announcement. So what I want to see in there are user visible changes. High level.
> So if I look at https://github.com/Subsurface-divelog/subsurface/pull/1091 I'd say that prior to applying the patch we had maybe too little detail. The PR skirts being more verbose than I like, but I think it stays just barely on the good side of things. My suggested changes would be basically nit-picking. E.g., combine line 21+22, maybe drop line 19...
>

i have merged it. changes can be applied once copying to the ReleaseNotes files.

lubomir
--


More information about the subsurface mailing list