Re: Changing editors draft workflow

I'd autogenerate from the commit logs if possible. We WILL have commits
that have messy descriptions, so there's a manual step needed somewhere.

Off the top of my head:

- Commits from $TOKEN to tip-of-tree get automatically added to the
changelog
- When we mess up the automatic log, the editor can revise the changelog
and move $TOKEN to the last commit that is manually reviewed

It would be great if we could avoid having the changelog in the master
HTML file. File included at generation time?

On 10/10/2017 02:30 PM, Daniel Burnett wrote:
>
>
> On Tue, Oct 10, 2017 at 1:03 AM, Adam Bergkvist
> <adam.bergkvist@ericsson.com <mailto: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 <mailto: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
>
>

-- 
Surveillance is pervasive. Go Dark.