Re: Changing editors draft workflow

On Tue, Oct 10, 2017 at 1:03 AM, Adam Bergkvist <adam.bergkvist@ericsson.com
> wrote:

> On 2017-10-10 01:37, Cullen Jennings (fluffy) wrote:
> >> On Oct 9, 2017, at 5:54 AM, Dominique Hazael-Massieux <dom@w3.org>
> wrote:
> >>
> >> Le 06/10/2017 à 22:58, Bernard Aboba a écrit :
> >>> To clarify, this would mean that for webrtc-pc (the only document not
> yet at CR) there would be an editors' draft for each commit to master,
> right?  But that would end once the document is published as a CR?
> >>>
> >>> [BA] How would change logs work?
> >> Good question; I think our options are:
> >> A. making the last step before a merge (or while doing the merge) that
> >> editors add a matching line to the changelog
> >> B. requiring them in pull requests, with a new format convention since
> >> we would be moving away from specific date release; hopefully that
> >> convention would avoid conflicts on merge (but I'm not too sure how)
> >> C. removing changelogs from the document
> >> D. having them updated at a different pace from editors draft (e.g.
> >> weekly? biweekly?)
> >> E. having them autogenerated from the commit logs (which would probably
> >> require some convention for the commit messages)
> >> F. having them maintained into a separate document
> >>
> >> I would start with D while we figure out which of the others would
> >> otherwise work better.
> >>
> >> Dom
> > I could live with any of the above but I think B makes the most sense to
> me.
>
> I'm leaning towards a combination of B and E. If we have well formatted
> PR titles I don't think it's super necessary to maintain a separate
> change log, but at the same time it shouldn't be to hard to have one
> automatically generated with a summary at one location that also filters
> out noise like minor editorial changes.
>
> Some thoughts:
>
> Can we have github labels or [keywords] in the commit message to filter
> which changes that should go into the change log? For example, typo
> fixes would be excluded.
>
> Regarding a convention for PR titles. I think it would work if the
> editors or the person reviewing a PR, also reviews the PR title and
> checks if it follows the convention and makes sense. That would be done
> all days of the week and not slow us down at the editor's call.
> Regardless which way we go, I think this should be done.
>

We need something like what Adam suggests.  In my experience, most PR
titles and commit messages make for terrible change logs, because their
purposes are different.  A commit message should describe the actual
change.  A change log description, as we've done it, should describe the
conceptual change.  The PR title comes closest to the latter, but often
multiple PRs together result in one conceptual change, or at least they
have in the past.  Hopefully that will be less true going forward.


>
> /Adam
>