commit message titles and changelog entries
Jan Mulder
jlmulder at xs4all.nl
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: 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.
>>
>> 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).
--jan
More information about the subsurface
mailing list