On 3 February 2018 at 17:41, Dirk Hohndel <[email protected]> wrote: > >> On Feb 3, 2018, at 2:29 AM, Jan Mulder <[email protected]> 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 -- _______________________________________________ subsurface mailing list [email protected] http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
