commit message titles and changelog entries

Jan Mulder jlmulder at
Sat Feb 3 02:29:13 PST 2018

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

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

Agree. No tooling required, but I was just curious about further plans 
with this.

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

But agree, the GitHub pushing to a PR of somebody else is nice, but at 
this moment I think that most of out contributors would be very 
surprised when they would receive a PR on their PR.

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


More information about the subsurface mailing list