Re: [VOTE] CHANGELOG.md file (second try)

[Rawlin Peters]

I think a "changelog" label is alright, but ideally I think individual
developers should apply their own discretion and edit the CHANGELOG.md
as part of their PR if they feel like it needs an entry. It might be
easier to write meaningful entries when it's still fresh in your mind
rather than 3-6 months down the road when you've already forgotten
what you changed. The label seems like it would allow people to wait
those 3-6 months until just before a release to go back through their
tagged PRs and add the info all at once.

One thing I'd like to avoid though is merge conflicts on the
CHANGELOG.md file from everyone writing to the same spot. For example,
OpenStack does something like this for their release notes, so we
could try to follow their example [1]. The tl;dr is that each entry
gets its own unique file in a releasenotes directory, then the release
notes are generated from compiling all the individual files. But, if
the rate of editing CHANGELOG.md is low, dealing with the occasional
merge conflict might be easier than the tooling.

- Rawlin

[1] https://docs.openstack.org/reno/latest/user/usage.html

On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts  wrote:
> +1. To clarify, I'm +1 on having the "changelog" label, to help whoever
> manually goes thru and builds the CHANGELOG.md.
>
> But I agree with @neuman I don't think we can automate this. Titles are too
> short, some changes need longer explanations and some don't, only a human
> can figure out how important something is to users; a high priority bug fix
> could still be low-impact, or vica-versa. Much as I dislike manual things,
> this really needs human judgement. And we absolutely need a good Changelog
> with each Release.
>
> On Thu, Dec 14, 2017 at 2:36 PM, Dave Neuman  wrote:
>
>> Thanks for putting that together Dewayne. I was just starting to do that
>> myself when I saw it was already done.
>> As a developer this is fine, I can see a list of PRs and click on each one
>> to see the whole conversation.  I can comb through them and get a general
>> sense for what changed.
>>
>> However, as an operator and user of Traffic Control (which I mostly am
>> these days) I am -1 for the following reasons:
>> 1) only committers can assign labels to issues and pull requests.  This
>> means that the committers need to be cognizant of the issues/PRs they are
>> reviewing and apply the change log label;
>> 2) the title of a PR only gives so much information about a change, if I
>> want more information I have to click on each individual one
>> 3) If I am not a developer, or someone who is very familiar with our
>> project, it is hard for me to ascertain from this list which changes are
>> super-important or have some operational considerations attached to them.
>> These are the issues I really care about.
>> 4) When I go to do an upgrade, it's a lot easier to copy/paste a nice
>> bulleted list of what changed then it is to try to take a list of PRs and
>> turn it into a high level list of what's important.
>>
>> We need a solution that gives someone what they need at a glance. Something
>> that can be copy/pasted out or easily linked to.  IMO not all of our users
>> are super technical or involved in the day to day so we shouldn't just
>> point them at a list of PRs and say "figure it out"; we should make it easy
>> for them to figure out.
>>
>> I have seen lots of alternatives suggested to what Steve has proposed, but
>> I haven't seen anyone state why they don't like what Steve has proposed?  I
>> think what he is proposing is pretty standard across major Github projects
>> that I have seen.  I understand that we can introduce some additional
>> inconvenience with having to manually write what your feature or bug fix
>> does, and there could be some conflicts, but isn't it important to clearly
>> portray what has changed?  I don't think we need a changelog.md entry to
>> every PR, in fact I hope we don't...we need a changelog.md entry any time
>> we add a new feature, any time we have some operational considerations that
>> need to be communicated, or any time that we fix a bug from a previous
>> release.
>>
>>
>> On Thu, Dec 14, 2017 at 2:02 PM, Jeremy Mitchell 
>> wrote:
>>
>> > This label idea would require everyone to go back and find their PRs that
>> > were closed after Aug 4th (the date 2.1 branch was created) and attach
>> the
>> > 'change log' label and the 2.2 milestone to the appropriate ones, right?
>> > And then that link dew provide would be an accurate picture of what has
>> > changed between 21. and 2.2...
>> >
>> > of course, ignore PRs that don't affect the "interface" like "license
>> > changes", right?
>> >
>> > i like the idea...
>> >
>> > On Thu, Dec 14, 2017 at 1:59 PM, Dewayne Richardson 
>> > wrote:
>> >
>> > > As a POC for the Change Log label follow this link:
>> > >
>> > > https://github.com/apache/incubator-trafficcontrol/
>> > > 

Re: [VOTE] CHANGELOG.md file (second try)

[Robert Butts]

+1. To clarify, I'm +1 on having the "changelog" label, to help whoever
manually goes thru and builds the CHANGELOG.md.

But I agree with @neuman I don't think we can automate this. Titles are too
short, some changes need longer explanations and some don't, only a human
can figure out how important something is to users; a high priority bug fix
could still be low-impact, or vica-versa. Much as I dislike manual things,
this really needs human judgement. And we absolutely need a good Changelog
with each Release.

On Thu, Dec 14, 2017 at 2:36 PM, Dave Neuman  wrote:

> Thanks for putting that together Dewayne. I was just starting to do that
> myself when I saw it was already done.
> As a developer this is fine, I can see a list of PRs and click on each one
> to see the whole conversation.  I can comb through them and get a general
> sense for what changed.
>
> However, as an operator and user of Traffic Control (which I mostly am
> these days) I am -1 for the following reasons:
> 1) only committers can assign labels to issues and pull requests.  This
> means that the committers need to be cognizant of the issues/PRs they are
> reviewing and apply the change log label;
> 2) the title of a PR only gives so much information about a change, if I
> want more information I have to click on each individual one
> 3) If I am not a developer, or someone who is very familiar with our
> project, it is hard for me to ascertain from this list which changes are
> super-important or have some operational considerations attached to them.
> These are the issues I really care about.
> 4) When I go to do an upgrade, it's a lot easier to copy/paste a nice
> bulleted list of what changed then it is to try to take a list of PRs and
> turn it into a high level list of what's important.
>
> We need a solution that gives someone what they need at a glance. Something
> that can be copy/pasted out or easily linked to.  IMO not all of our users
> are super technical or involved in the day to day so we shouldn't just
> point them at a list of PRs and say "figure it out"; we should make it easy
> for them to figure out.
>
> I have seen lots of alternatives suggested to what Steve has proposed, but
> I haven't seen anyone state why they don't like what Steve has proposed?  I
> think what he is proposing is pretty standard across major Github projects
> that I have seen.  I understand that we can introduce some additional
> inconvenience with having to manually write what your feature or bug fix
> does, and there could be some conflicts, but isn't it important to clearly
> portray what has changed?  I don't think we need a changelog.md entry to
> every PR, in fact I hope we don't...we need a changelog.md entry any time
> we add a new feature, any time we have some operational considerations that
> need to be communicated, or any time that we fix a bug from a previous
> release.
>
>
> On Thu, Dec 14, 2017 at 2:02 PM, Jeremy Mitchell 
> wrote:
>
> > This label idea would require everyone to go back and find their PRs that
> > were closed after Aug 4th (the date 2.1 branch was created) and attach
> the
> > 'change log' label and the 2.2 milestone to the appropriate ones, right?
> > And then that link dew provide would be an accurate picture of what has
> > changed between 21. and 2.2...
> >
> > of course, ignore PRs that don't affect the "interface" like "license
> > changes", right?
> >
> > i like the idea...
> >
> > On Thu, Dec 14, 2017 at 1:59 PM, Dewayne Richardson 
> > wrote:
> >
> > > As a POC for the Change Log label follow this link:
> > >
> > > https://github.com/apache/incubator-trafficcontrol/
> > > pulls?q=is%3Apr+is%3Aclosed+label%3A%22change+log%22+milestone%3A2.2.0
> > >
> > > -Dew
> > >
> > > On Thu, Dec 14, 2017 at 10:48 AM, Gelinas, Derek <
> > > derek_geli...@comcast.com>
> > > wrote:
> > >
> > > > I'm +1 for the label as well.
> > > >
> > > > > On Dec 14, 2017, at 12:29 PM, Robert Butts <
> robert.o.bu...@gmail.com
> > >
> > > > wrote:
> > > > >
> > > > > +1 on a "changelog" label. Seems like that would make it a lot
> easier
> > > for
> > > > > the person writing it up. Easier to skip things like code
> maintenance
> > > > that
> > > > > have no interface effect.
> > > > >
> > > > > On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson <
> > > dewr...@gmail.com>
> > > > > wrote:
> > > > >
> > > > >> Another idea would be to include a new CHANGELOG label that you
> > could
> > > > tack
> > > > >> onto specific PR's that you wanted to be included (as well as
> > grouped
> > > > >> within Milestones) as the high level features that went into the
> > > > release.
> > > > >> As for the gotchas, I think those should be Github issues because
> to
> > > me
> > > > >> those were bugs.
> > > > >>
> > > > >> -Dew
> > > > >>
> > > > >> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell <
> > > > mitchell...@gmail.com>
> > > > >> wrote:
> > > > >>
> > > > >>> I agree. Very 

Re: [VOTE] CHANGELOG.md file (second try)

[Dave Neuman]

Thanks for putting that together Dewayne. I was just starting to do that
myself when I saw it was already done.
As a developer this is fine, I can see a list of PRs and click on each one
to see the whole conversation.  I can comb through them and get a general
sense for what changed.

However, as an operator and user of Traffic Control (which I mostly am
these days) I am -1 for the following reasons:
1) only committers can assign labels to issues and pull requests.  This
means that the committers need to be cognizant of the issues/PRs they are
reviewing and apply the change log label;
2) the title of a PR only gives so much information about a change, if I
want more information I have to click on each individual one
3) If I am not a developer, or someone who is very familiar with our
project, it is hard for me to ascertain from this list which changes are
super-important or have some operational considerations attached to them.
These are the issues I really care about.
4) When I go to do an upgrade, it's a lot easier to copy/paste a nice
bulleted list of what changed then it is to try to take a list of PRs and
turn it into a high level list of what's important.

We need a solution that gives someone what they need at a glance. Something
that can be copy/pasted out or easily linked to.  IMO not all of our users
are super technical or involved in the day to day so we shouldn't just
point them at a list of PRs and say "figure it out"; we should make it easy
for them to figure out.

I have seen lots of alternatives suggested to what Steve has proposed, but
I haven't seen anyone state why they don't like what Steve has proposed?  I
think what he is proposing is pretty standard across major Github projects
that I have seen.  I understand that we can introduce some additional
inconvenience with having to manually write what your feature or bug fix
does, and there could be some conflicts, but isn't it important to clearly
portray what has changed?  I don't think we need a changelog.md entry to
every PR, in fact I hope we don't...we need a changelog.md entry any time
we add a new feature, any time we have some operational considerations that
need to be communicated, or any time that we fix a bug from a previous
release.


On Thu, Dec 14, 2017 at 2:02 PM, Jeremy Mitchell 
wrote:

> This label idea would require everyone to go back and find their PRs that
> were closed after Aug 4th (the date 2.1 branch was created) and attach the
> 'change log' label and the 2.2 milestone to the appropriate ones, right?
> And then that link dew provide would be an accurate picture of what has
> changed between 21. and 2.2...
>
> of course, ignore PRs that don't affect the "interface" like "license
> changes", right?
>
> i like the idea...
>
> On Thu, Dec 14, 2017 at 1:59 PM, Dewayne Richardson 
> wrote:
>
> > As a POC for the Change Log label follow this link:
> >
> > https://github.com/apache/incubator-trafficcontrol/
> > pulls?q=is%3Apr+is%3Aclosed+label%3A%22change+log%22+milestone%3A2.2.0
> >
> > -Dew
> >
> > On Thu, Dec 14, 2017 at 10:48 AM, Gelinas, Derek <
> > derek_geli...@comcast.com>
> > wrote:
> >
> > > I'm +1 for the label as well.
> > >
> > > > On Dec 14, 2017, at 12:29 PM, Robert Butts  >
> > > wrote:
> > > >
> > > > +1 on a "changelog" label. Seems like that would make it a lot easier
> > for
> > > > the person writing it up. Easier to skip things like code maintenance
> > > that
> > > > have no interface effect.
> > > >
> > > > On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson <
> > dewr...@gmail.com>
> > > > wrote:
> > > >
> > > >> Another idea would be to include a new CHANGELOG label that you
> could
> > > tack
> > > >> onto specific PR's that you wanted to be included (as well as
> grouped
> > > >> within Milestones) as the high level features that went into the
> > > release.
> > > >> As for the gotchas, I think those should be Github issues because to
> > me
> > > >> those were bugs.
> > > >>
> > > >> -Dew
> > > >>
> > > >> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell <
> > > mitchell...@gmail.com>
> > > >> wrote:
> > > >>
> > > >>> I agree. Very readable. I also like the idea of a either creating a
> > > >>> CHANGELOG.md for each component...or one CHANGELOG.md with sections
> > for
> > > >>> each component.
> > > >>>
> > > >>> I still do like the idea of creating issues with milestones but
> I'll
> > > let
> > > >>> that go. That seems to be a personal preference of mine.
> > > >>>
> > > >>> Jeremy
> > > >>>
> > >  On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman 
> > > wrote:
> > > 
> > >  Have you taken a look at some Changelogs of other github projects?
> > > >> Here
> > >  are a few from other projects we use in Traffic Control:
> > >  - Docker Compose: https://github.com/docker/
> > > >>> compose/blob/master/CHANGELOG.
> > >  md
> > >  - InfluxDB: 

Re: [VOTE] CHANGELOG.md file (second try)

[Dan Kirkwood]

+1 as well...

This query should show all PRs merged since the 2.1 branch:

https://github.com/apache/incubator-trafficcontrol/pulls?utf8=%E2%9C%93=is%3Apr+is%3Aclosed+merged%3A%3E%3D2017-08-04+base%3Amaster

On Thu, Dec 14, 2017 at 2:02 PM, Jeremy Mitchell  wrote:
> This label idea would require everyone to go back and find their PRs that
> were closed after Aug 4th (the date 2.1 branch was created) and attach the
> 'change log' label and the 2.2 milestone to the appropriate ones, right?
> And then that link dew provide would be an accurate picture of what has
> changed between 21. and 2.2...
>
> of course, ignore PRs that don't affect the "interface" like "license
> changes", right?
>
> i like the idea...
>
> On Thu, Dec 14, 2017 at 1:59 PM, Dewayne Richardson 
> wrote:
>
>> As a POC for the Change Log label follow this link:
>>
>> https://github.com/apache/incubator-trafficcontrol/
>> pulls?q=is%3Apr+is%3Aclosed+label%3A%22change+log%22+milestone%3A2.2.0
>>
>> -Dew
>>
>> On Thu, Dec 14, 2017 at 10:48 AM, Gelinas, Derek <
>> derek_geli...@comcast.com>
>> wrote:
>>
>> > I'm +1 for the label as well.
>> >
>> > > On Dec 14, 2017, at 12:29 PM, Robert Butts 
>> > wrote:
>> > >
>> > > +1 on a "changelog" label. Seems like that would make it a lot easier
>> for
>> > > the person writing it up. Easier to skip things like code maintenance
>> > that
>> > > have no interface effect.
>> > >
>> > > On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson <
>> dewr...@gmail.com>
>> > > wrote:
>> > >
>> > >> Another idea would be to include a new CHANGELOG label that you could
>> > tack
>> > >> onto specific PR's that you wanted to be included (as well as grouped
>> > >> within Milestones) as the high level features that went into the
>> > release.
>> > >> As for the gotchas, I think those should be Github issues because to
>> me
>> > >> those were bugs.
>> > >>
>> > >> -Dew
>> > >>
>> > >> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell <
>> > mitchell...@gmail.com>
>> > >> wrote:
>> > >>
>> > >>> I agree. Very readable. I also like the idea of a either creating a
>> > >>> CHANGELOG.md for each component...or one CHANGELOG.md with sections
>> for
>> > >>> each component.
>> > >>>
>> > >>> I still do like the idea of creating issues with milestones but I'll
>> > let
>> > >>> that go. That seems to be a personal preference of mine.
>> > >>>
>> > >>> Jeremy
>> > >>>
>> >  On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman 
>> > wrote:
>> > 
>> >  Have you taken a look at some Changelogs of other github projects?
>> > >> Here
>> >  are a few from other projects we use in Traffic Control:
>> >  - Docker Compose: https://github.com/docker/
>> > >>> compose/blob/master/CHANGELOG.
>> >  md
>> >  - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
>> >  CHANGELOG.md
>> >  - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG
>> .
>> > md
>> >  - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.
>> md
>> > 
>> >  See how easy to read those are and how they provide a lot of
>> > >> information
>> >  without having to wade through hundreds of issues and pull requests?
>> > >>> Some
>> >  of them also have links to issues for new features, as well as bug
>> > >> fixes
>> >  that are in the current release.  I think all of them are easy to
>> read
>> > >>> and
>> >  can give a user a quick overview of what is in the new release. I
>> > think
>> >  it's fine to add a link to all the issues if we want, but I think
>> >  ultimately we want to create something like what I have linked to
>> > >> above.
>> >  We might also want to break out our CHANGELOG.md by component to
>> > >> provide
>> >  even more readability.
>> > 
>> >  I know our first inclination is to try to automate everything, but
>> >  sometimes it makes sense to do things manually so that you can
>> create
>> > a
>> >  better output.
>> > 
>> > 
>> > 
>> >  On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell <
>> > >> mitchell...@gmail.com>
>> >  wrote:
>> > 
>> > > What if CHANGLOG.md includes 2 things:
>> > >
>> > > 1. a link to 2.2 issues (i.e.
>> > > https://github.com/apache/incubator-trafficcontrol/
>> > > issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
>> > > 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
>> >  connect
>> > > to a Riak with self-signed certificates; Riak security grant needs
>> >  updated;
>> > > upgrade param needed for ds routing names, etc, etc...)
>> > >
>> > > But again this requires everyone to create issues (with a
>> milestone)
>> > >> in
>> > > which one or more PR's can be attached to.
>> > >
>> > > Dave, you said "If you are developing a new feature you could
>> easily
>> > >>> end
>> >  up
>> > > with 5 or more PRs"

Re: [VOTE] CHANGELOG.md file (second try)

[Jeremy Mitchell]

This label idea would require everyone to go back and find their PRs that
were closed after Aug 4th (the date 2.1 branch was created) and attach the
'change log' label and the 2.2 milestone to the appropriate ones, right?
And then that link dew provide would be an accurate picture of what has
changed between 21. and 2.2...

of course, ignore PRs that don't affect the "interface" like "license
changes", right?

i like the idea...

On Thu, Dec 14, 2017 at 1:59 PM, Dewayne Richardson 
wrote:

> As a POC for the Change Log label follow this link:
>
> https://github.com/apache/incubator-trafficcontrol/
> pulls?q=is%3Apr+is%3Aclosed+label%3A%22change+log%22+milestone%3A2.2.0
>
> -Dew
>
> On Thu, Dec 14, 2017 at 10:48 AM, Gelinas, Derek <
> derek_geli...@comcast.com>
> wrote:
>
> > I'm +1 for the label as well.
> >
> > > On Dec 14, 2017, at 12:29 PM, Robert Butts 
> > wrote:
> > >
> > > +1 on a "changelog" label. Seems like that would make it a lot easier
> for
> > > the person writing it up. Easier to skip things like code maintenance
> > that
> > > have no interface effect.
> > >
> > > On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson <
> dewr...@gmail.com>
> > > wrote:
> > >
> > >> Another idea would be to include a new CHANGELOG label that you could
> > tack
> > >> onto specific PR's that you wanted to be included (as well as grouped
> > >> within Milestones) as the high level features that went into the
> > release.
> > >> As for the gotchas, I think those should be Github issues because to
> me
> > >> those were bugs.
> > >>
> > >> -Dew
> > >>
> > >> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell <
> > mitchell...@gmail.com>
> > >> wrote:
> > >>
> > >>> I agree. Very readable. I also like the idea of a either creating a
> > >>> CHANGELOG.md for each component...or one CHANGELOG.md with sections
> for
> > >>> each component.
> > >>>
> > >>> I still do like the idea of creating issues with milestones but I'll
> > let
> > >>> that go. That seems to be a personal preference of mine.
> > >>>
> > >>> Jeremy
> > >>>
> >  On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman 
> > wrote:
> > 
> >  Have you taken a look at some Changelogs of other github projects?
> > >> Here
> >  are a few from other projects we use in Traffic Control:
> >  - Docker Compose: https://github.com/docker/
> > >>> compose/blob/master/CHANGELOG.
> >  md
> >  - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
> >  CHANGELOG.md
> >  - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG
> .
> > md
> >  - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.
> md
> > 
> >  See how easy to read those are and how they provide a lot of
> > >> information
> >  without having to wade through hundreds of issues and pull requests?
> > >>> Some
> >  of them also have links to issues for new features, as well as bug
> > >> fixes
> >  that are in the current release.  I think all of them are easy to
> read
> > >>> and
> >  can give a user a quick overview of what is in the new release. I
> > think
> >  it's fine to add a link to all the issues if we want, but I think
> >  ultimately we want to create something like what I have linked to
> > >> above.
> >  We might also want to break out our CHANGELOG.md by component to
> > >> provide
> >  even more readability.
> > 
> >  I know our first inclination is to try to automate everything, but
> >  sometimes it makes sense to do things manually so that you can
> create
> > a
> >  better output.
> > 
> > 
> > 
> >  On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell <
> > >> mitchell...@gmail.com>
> >  wrote:
> > 
> > > What if CHANGLOG.md includes 2 things:
> > >
> > > 1. a link to 2.2 issues (i.e.
> > > https://github.com/apache/incubator-trafficcontrol/
> > > issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> > > 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
> >  connect
> > > to a Riak with self-signed certificates; Riak security grant needs
> >  updated;
> > > upgrade param needed for ds routing names, etc, etc...)
> > >
> > > But again this requires everyone to create issues (with a
> milestone)
> > >> in
> > > which one or more PR's can be attached to.
> > >
> > > Dave, you said "If you are developing a new feature you could
> easily
> > >>> end
> >  up
> > > with 5 or more PRs"
> > >
> > > So in this case, I'd expect 1 issue and 5 PR's linked to that 1
> > >>> issue...
> > >
> > > Jeremy
> > >
> > > On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman 
> > >>> wrote:
> > >
> > >> I think it's fine to include all of our PRs and issues in a github
> > >> milestone, and we should do that, but I don't think that we want
> to
> > > include
> > >> every 

Re: [VOTE] CHANGELOG.md file (second try)

[Dewayne Richardson]

As a POC for the Change Log label follow this link:

https://github.com/apache/incubator-trafficcontrol/pulls?q=is%3Apr+is%3Aclosed+label%3A%22change+log%22+milestone%3A2.2.0

-Dew

On Thu, Dec 14, 2017 at 10:48 AM, Gelinas, Derek 
wrote:

> I'm +1 for the label as well.
>
> > On Dec 14, 2017, at 12:29 PM, Robert Butts 
> wrote:
> >
> > +1 on a "changelog" label. Seems like that would make it a lot easier for
> > the person writing it up. Easier to skip things like code maintenance
> that
> > have no interface effect.
> >
> > On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson 
> > wrote:
> >
> >> Another idea would be to include a new CHANGELOG label that you could
> tack
> >> onto specific PR's that you wanted to be included (as well as grouped
> >> within Milestones) as the high level features that went into the
> release.
> >> As for the gotchas, I think those should be Github issues because to me
> >> those were bugs.
> >>
> >> -Dew
> >>
> >> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell <
> mitchell...@gmail.com>
> >> wrote:
> >>
> >>> I agree. Very readable. I also like the idea of a either creating a
> >>> CHANGELOG.md for each component...or one CHANGELOG.md with sections for
> >>> each component.
> >>>
> >>> I still do like the idea of creating issues with milestones but I'll
> let
> >>> that go. That seems to be a personal preference of mine.
> >>>
> >>> Jeremy
> >>>
>  On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman 
> wrote:
> 
>  Have you taken a look at some Changelogs of other github projects?
> >> Here
>  are a few from other projects we use in Traffic Control:
>  - Docker Compose: https://github.com/docker/
> >>> compose/blob/master/CHANGELOG.
>  md
>  - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
>  CHANGELOG.md
>  - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG.
> md
>  - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
> 
>  See how easy to read those are and how they provide a lot of
> >> information
>  without having to wade through hundreds of issues and pull requests?
> >>> Some
>  of them also have links to issues for new features, as well as bug
> >> fixes
>  that are in the current release.  I think all of them are easy to read
> >>> and
>  can give a user a quick overview of what is in the new release. I
> think
>  it's fine to add a link to all the issues if we want, but I think
>  ultimately we want to create something like what I have linked to
> >> above.
>  We might also want to break out our CHANGELOG.md by component to
> >> provide
>  even more readability.
> 
>  I know our first inclination is to try to automate everything, but
>  sometimes it makes sense to do things manually so that you can create
> a
>  better output.
> 
> 
> 
>  On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell <
> >> mitchell...@gmail.com>
>  wrote:
> 
> > What if CHANGLOG.md includes 2 things:
> >
> > 1. a link to 2.2 issues (i.e.
> > https://github.com/apache/incubator-trafficcontrol/
> > issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> > 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
>  connect
> > to a Riak with self-signed certificates; Riak security grant needs
>  updated;
> > upgrade param needed for ds routing names, etc, etc...)
> >
> > But again this requires everyone to create issues (with a milestone)
> >> in
> > which one or more PR's can be attached to.
> >
> > Dave, you said "If you are developing a new feature you could easily
> >>> end
>  up
> > with 5 or more PRs"
> >
> > So in this case, I'd expect 1 issue and 5 PR's linked to that 1
> >>> issue...
> >
> > Jeremy
> >
> > On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman 
> >>> wrote:
> >
> >> I think it's fine to include all of our PRs and issues in a github
> >> milestone, and we should do that, but I don't think that we want to
> > include
> >> every single PR in our changelog.  When we have tried that in the
> >>> past
>  we
> >> have realized that it gets to be so much information that it's not
> > useful.
> >> A good example of why is a new feature. If you are developing a new
> > feature
> >> you could easily end up with 5 or more PRs: one to introduce the
>  feature,
> >> one to add some more functionality, several to fix bugs with it,
> >> etc.
> >> Instead of having a line in the changelog for each one of those
> >> PRs,
> >>> we
> >> should just have one line that says "introduced feature X" with
> >>> maybe a
> >> blurb about what it is and any release notes that an operator would
>  need
> > to
> >> know.  This way the file in concise and easy to 

Re: [VOTE] CHANGELOG.md file (second try)

[Gelinas, Derek]

I'm +1 for the label as well.

> On Dec 14, 2017, at 12:29 PM, Robert Butts  wrote:
> 
> +1 on a "changelog" label. Seems like that would make it a lot easier for
> the person writing it up. Easier to skip things like code maintenance that
> have no interface effect.
> 
> On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson 
> wrote:
> 
>> Another idea would be to include a new CHANGELOG label that you could tack
>> onto specific PR's that you wanted to be included (as well as grouped
>> within Milestones) as the high level features that went into the release.
>> As for the gotchas, I think those should be Github issues because to me
>> those were bugs.
>> 
>> -Dew
>> 
>> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell 
>> wrote:
>> 
>>> I agree. Very readable. I also like the idea of a either creating a
>>> CHANGELOG.md for each component...or one CHANGELOG.md with sections for
>>> each component.
>>> 
>>> I still do like the idea of creating issues with milestones but I'll let
>>> that go. That seems to be a personal preference of mine.
>>> 
>>> Jeremy
>>> 
 On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman  wrote:
 
 Have you taken a look at some Changelogs of other github projects?
>> Here
 are a few from other projects we use in Traffic Control:
 - Docker Compose: https://github.com/docker/
>>> compose/blob/master/CHANGELOG.
 md
 - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
 CHANGELOG.md
 - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG.md
 - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
 
 See how easy to read those are and how they provide a lot of
>> information
 without having to wade through hundreds of issues and pull requests?
>>> Some
 of them also have links to issues for new features, as well as bug
>> fixes
 that are in the current release.  I think all of them are easy to read
>>> and
 can give a user a quick overview of what is in the new release. I think
 it's fine to add a link to all the issues if we want, but I think
 ultimately we want to create something like what I have linked to
>> above.
 We might also want to break out our CHANGELOG.md by component to
>> provide
 even more readability.
 
 I know our first inclination is to try to automate everything, but
 sometimes it makes sense to do things manually so that you can create a
 better output.
 
 
 
 On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell <
>> mitchell...@gmail.com>
 wrote:
 
> What if CHANGLOG.md includes 2 things:
> 
> 1. a link to 2.2 issues (i.e.
> https://github.com/apache/incubator-trafficcontrol/
> issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
 connect
> to a Riak with self-signed certificates; Riak security grant needs
 updated;
> upgrade param needed for ds routing names, etc, etc...)
> 
> But again this requires everyone to create issues (with a milestone)
>> in
> which one or more PR's can be attached to.
> 
> Dave, you said "If you are developing a new feature you could easily
>>> end
 up
> with 5 or more PRs"
> 
> So in this case, I'd expect 1 issue and 5 PR's linked to that 1
>>> issue...
> 
> Jeremy
> 
> On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman 
>>> wrote:
> 
>> I think it's fine to include all of our PRs and issues in a github
>> milestone, and we should do that, but I don't think that we want to
> include
>> every single PR in our changelog.  When we have tried that in the
>>> past
 we
>> have realized that it gets to be so much information that it's not
> useful.
>> A good example of why is a new feature. If you are developing a new
> feature
>> you could easily end up with 5 or more PRs: one to introduce the
 feature,
>> one to add some more functionality, several to fix bugs with it,
>> etc.
>> Instead of having a line in the changelog for each one of those
>> PRs,
>>> we
>> should just have one line that says "introduced feature X" with
>>> maybe a
>> blurb about what it is and any release notes that an operator would
 need
> to
>> know.  This way the file in concise and easy to understand by
>> anyone
>> wanting to use a new version of our product.  I think it's also
 important
>> to include what bug fixes (since the previous release) that we have
> fixed.
>> Those are the reasons why I tend to lean towards a manual
>> changelog.
 It
>> gives us the ability to control how much information goes into the
>> changelog and the flexibility to make sure it is useful.
>> 
>> On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell <
 

Re: [VOTE] CHANGELOG.md file (second try)

[Robert Butts]

+1 on a "changelog" label. Seems like that would make it a lot easier for
the person writing it up. Easier to skip things like code maintenance that
have no interface effect.

On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson 
wrote:

> Another idea would be to include a new CHANGELOG label that you could tack
> onto specific PR's that you wanted to be included (as well as grouped
> within Milestones) as the high level features that went into the release.
> As for the gotchas, I think those should be Github issues because to me
> those were bugs.
>
> -Dew
>
> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell 
> wrote:
>
> > I agree. Very readable. I also like the idea of a either creating a
> > CHANGELOG.md for each component...or one CHANGELOG.md with sections for
> > each component.
> >
> > I still do like the idea of creating issues with milestones but I'll let
> > that go. That seems to be a personal preference of mine.
> >
> > Jeremy
> >
> > On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman  wrote:
> >
> > > Have you taken a look at some Changelogs of other github projects?
> Here
> > > are a few from other projects we use in Traffic Control:
> > > - Docker Compose: https://github.com/docker/
> > compose/blob/master/CHANGELOG.
> > > md
> > > - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
> > > CHANGELOG.md
> > > - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG.md
> > > - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
> > >
> > > See how easy to read those are and how they provide a lot of
> information
> > > without having to wade through hundreds of issues and pull requests?
> > Some
> > > of them also have links to issues for new features, as well as bug
> fixes
> > > that are in the current release.  I think all of them are easy to read
> > and
> > > can give a user a quick overview of what is in the new release. I think
> > > it's fine to add a link to all the issues if we want, but I think
> > > ultimately we want to create something like what I have linked to
> above.
> > > We might also want to break out our CHANGELOG.md by component to
> provide
> > > even more readability.
> > >
> > > I know our first inclination is to try to automate everything, but
> > > sometimes it makes sense to do things manually so that you can create a
> > > better output.
> > >
> > >
> > >
> > > On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell <
> mitchell...@gmail.com>
> > > wrote:
> > >
> > > > What if CHANGLOG.md includes 2 things:
> > > >
> > > > 1. a link to 2.2 issues (i.e.
> > > > https://github.com/apache/incubator-trafficcontrol/
> > > > issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> > > > 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
> > > connect
> > > > to a Riak with self-signed certificates; Riak security grant needs
> > > updated;
> > > > upgrade param needed for ds routing names, etc, etc...)
> > > >
> > > > But again this requires everyone to create issues (with a milestone)
> in
> > > > which one or more PR's can be attached to.
> > > >
> > > > Dave, you said "If you are developing a new feature you could easily
> > end
> > > up
> > > > with 5 or more PRs"
> > > >
> > > > So in this case, I'd expect 1 issue and 5 PR's linked to that 1
> > issue...
> > > >
> > > > Jeremy
> > > >
> > > > On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman 
> > wrote:
> > > >
> > > > > I think it's fine to include all of our PRs and issues in a github
> > > > > milestone, and we should do that, but I don't think that we want to
> > > > include
> > > > > every single PR in our changelog.  When we have tried that in the
> > past
> > > we
> > > > > have realized that it gets to be so much information that it's not
> > > > useful.
> > > > > A good example of why is a new feature. If you are developing a new
> > > > feature
> > > > > you could easily end up with 5 or more PRs: one to introduce the
> > > feature,
> > > > > one to add some more functionality, several to fix bugs with it,
> etc.
> > > > > Instead of having a line in the changelog for each one of those
> PRs,
> > we
> > > > > should just have one line that says "introduced feature X" with
> > maybe a
> > > > > blurb about what it is and any release notes that an operator would
> > > need
> > > > to
> > > > > know.  This way the file in concise and easy to understand by
> anyone
> > > > > wanting to use a new version of our product.  I think it's also
> > > important
> > > > > to include what bug fixes (since the previous release) that we have
> > > > fixed.
> > > > > Those are the reasons why I tend to lean towards a manual
> changelog.
> > > It
> > > > > gives us the ability to control how much information goes into the
> > > > > changelog and the flexibility to make sure it is useful.
> > > > >
> > > > > On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell <
> > > mitchell...@gmail.com>
> > > > > wrote:
> > > > >

Re: [VOTE] CHANGELOG.md file (second try)

[Dewayne Richardson]

Another idea would be to include a new CHANGELOG label that you could tack
onto specific PR's that you wanted to be included (as well as grouped
within Milestones) as the high level features that went into the release.
As for the gotchas, I think those should be Github issues because to me
those were bugs.

-Dew

On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell 
wrote:

> I agree. Very readable. I also like the idea of a either creating a
> CHANGELOG.md for each component...or one CHANGELOG.md with sections for
> each component.
>
> I still do like the idea of creating issues with milestones but I'll let
> that go. That seems to be a personal preference of mine.
>
> Jeremy
>
> On Thu, Dec 14, 2017 at 9:45 AM, Dave Neuman  wrote:
>
> > Have you taken a look at some Changelogs of other github projects?  Here
> > are a few from other projects we use in Traffic Control:
> > - Docker Compose: https://github.com/docker/
> compose/blob/master/CHANGELOG.
> > md
> > - InfluxDB: https://github.com/influxdata/influxdb/blob/master/
> > CHANGELOG.md
> > - Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG.md
> > - Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
> >
> > See how easy to read those are and how they provide a lot of information
> > without having to wade through hundreds of issues and pull requests?
> Some
> > of them also have links to issues for new features, as well as bug fixes
> > that are in the current release.  I think all of them are easy to read
> and
> > can give a user a quick overview of what is in the new release. I think
> > it's fine to add a link to all the issues if we want, but I think
> > ultimately we want to create something like what I have linked to above.
> > We might also want to break out our CHANGELOG.md by component to provide
> > even more readability.
> >
> > I know our first inclination is to try to automate everything, but
> > sometimes it makes sense to do things manually so that you can create a
> > better output.
> >
> >
> >
> > On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell 
> > wrote:
> >
> > > What if CHANGLOG.md includes 2 things:
> > >
> > > 1. a link to 2.2 issues (i.e.
> > > https://github.com/apache/incubator-trafficcontrol/
> > > issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> > > 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't
> > connect
> > > to a Riak with self-signed certificates; Riak security grant needs
> > updated;
> > > upgrade param needed for ds routing names, etc, etc...)
> > >
> > > But again this requires everyone to create issues (with a milestone) in
> > > which one or more PR's can be attached to.
> > >
> > > Dave, you said "If you are developing a new feature you could easily
> end
> > up
> > > with 5 or more PRs"
> > >
> > > So in this case, I'd expect 1 issue and 5 PR's linked to that 1
> issue...
> > >
> > > Jeremy
> > >
> > > On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman 
> wrote:
> > >
> > > > I think it's fine to include all of our PRs and issues in a github
> > > > milestone, and we should do that, but I don't think that we want to
> > > include
> > > > every single PR in our changelog.  When we have tried that in the
> past
> > we
> > > > have realized that it gets to be so much information that it's not
> > > useful.
> > > > A good example of why is a new feature. If you are developing a new
> > > feature
> > > > you could easily end up with 5 or more PRs: one to introduce the
> > feature,
> > > > one to add some more functionality, several to fix bugs with it, etc.
> > > > Instead of having a line in the changelog for each one of those PRs,
> we
> > > > should just have one line that says "introduced feature X" with
> maybe a
> > > > blurb about what it is and any release notes that an operator would
> > need
> > > to
> > > > know.  This way the file in concise and easy to understand by anyone
> > > > wanting to use a new version of our product.  I think it's also
> > important
> > > > to include what bug fixes (since the previous release) that we have
> > > fixed.
> > > > Those are the reasons why I tend to lean towards a manual changelog.
> > It
> > > > gives us the ability to control how much information goes into the
> > > > changelog and the flexibility to make sure it is useful.
> > > >
> > > > On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell <
> > mitchell...@gmail.com>
> > > > wrote:
> > > >
> > > > > Why not leverage Github issues/milestones to determine the scope of
> > > each
> > > > > release? Per our CONTRIBUTING.md
> > > > >  > > > > master/CONTRIBUTING.md>
> > > > > :
> > > > >
> > > > > "If you have improvements (enhancements or bug fixes) for Traffic
> > > > Control,
> > > > > start by creating an issue
> > > > > ..."
> > > > >
> > > > > That implies that all 

Re: [VOTE] CHANGELOG.md file (second try)

[Dave Neuman]

Have you taken a look at some Changelogs of other github projects?  Here
are a few from other projects we use in Traffic Control:
- Docker Compose: https://github.com/docker/compose/blob/master/CHANGELOG.md
- InfluxDB: https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md
- Grafana: https://github.com/grafana/grafana/blob/master/CHANGELOG.md
- Ansible: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md

See how easy to read those are and how they provide a lot of information
without having to wade through hundreds of issues and pull requests?  Some
of them also have links to issues for new features, as well as bug fixes
that are in the current release.  I think all of them are easy to read and
can give a user a quick overview of what is in the new release. I think
it's fine to add a link to all the issues if we want, but I think
ultimately we want to create something like what I have linked to above.
We might also want to break out our CHANGELOG.md by component to provide
even more readability.

I know our first inclination is to try to automate everything, but
sometimes it makes sense to do things manually so that you can create a
better output.



On Thu, Dec 14, 2017 at 8:55 AM, Jeremy Mitchell 
wrote:

> What if CHANGLOG.md includes 2 things:
>
> 1. a link to 2.2 issues (i.e.
> https://github.com/apache/incubator-trafficcontrol/
> issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
> 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't connect
> to a Riak with self-signed certificates; Riak security grant needs updated;
> upgrade param needed for ds routing names, etc, etc...)
>
> But again this requires everyone to create issues (with a milestone) in
> which one or more PR's can be attached to.
>
> Dave, you said "If you are developing a new feature you could easily end up
> with 5 or more PRs"
>
> So in this case, I'd expect 1 issue and 5 PR's linked to that 1 issue...
>
> Jeremy
>
> On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman  wrote:
>
> > I think it's fine to include all of our PRs and issues in a github
> > milestone, and we should do that, but I don't think that we want to
> include
> > every single PR in our changelog.  When we have tried that in the past we
> > have realized that it gets to be so much information that it's not
> useful.
> > A good example of why is a new feature. If you are developing a new
> feature
> > you could easily end up with 5 or more PRs: one to introduce the feature,
> > one to add some more functionality, several to fix bugs with it, etc.
> > Instead of having a line in the changelog for each one of those PRs, we
> > should just have one line that says "introduced feature X" with maybe a
> > blurb about what it is and any release notes that an operator would need
> to
> > know.  This way the file in concise and easy to understand by anyone
> > wanting to use a new version of our product.  I think it's also important
> > to include what bug fixes (since the previous release) that we have
> fixed.
> > Those are the reasons why I tend to lean towards a manual changelog.  It
> > gives us the ability to control how much information goes into the
> > changelog and the flexibility to make sure it is useful.
> >
> > On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell 
> > wrote:
> >
> > > Why not leverage Github issues/milestones to determine the scope of
> each
> > > release? Per our CONTRIBUTING.md
> > >  > > master/CONTRIBUTING.md>
> > > :
> > >
> > > "If you have improvements (enhancements or bug fixes) for Traffic
> > Control,
> > > start by creating an issue
> > > ..."
> > >
> > > That implies that all PR's should be mapped to an issue although we do
> > not
> > > enforce this but if we did it would be easy to put each issue into a
> > > milestone (2.2 for example) and then pull a github report at any time.
> > >
> > > Orrather than creating an issue, put a good title/description on
> your
> > > PR and then the PR can be assigned to the milestone instead.
> > >
> > > It just seems like that's what milestones are for so why not use them?
> > >
> > > Jeremy
> > >
> > >
> > >
> > > On Wed, Dec 13, 2017 at 3:28 PM, Dave Neuman 
> wrote:
> > >
> > > > I am +1 on this approach, I know it's manual and there could be
> > conflicts
> > > > and it's a bit of a PITA, but I think it actually has some benefits
> in
> > > that
> > > > a human can actually enter in important release notes that are
> readable
> > > and
> > > > make sense.
> > > > That being said if someone is willing to make an automated approach
> > work,
> > > > that allows us to keep track of changes at a reasonable level (not
> per
> > > > commit, not necessarily even per PR), then I could be +1 on that as
> > well.
> > > > I would need to someone volunteer to make it work before I 

Re: [VOTE] CHANGELOG.md file (second try)

[Jeremy Mitchell]

What if CHANGLOG.md includes 2 things:

1. a link to 2.2 issues (i.e.
https://github.com/apache/incubator-trafficcontrol/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0
2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang doesn't connect
to a Riak with self-signed certificates; Riak security grant needs updated;
upgrade param needed for ds routing names, etc, etc...)

But again this requires everyone to create issues (with a milestone) in
which one or more PR's can be attached to.

Dave, you said "If you are developing a new feature you could easily end up
with 5 or more PRs"

So in this case, I'd expect 1 issue and 5 PR's linked to that 1 issue...

Jeremy

On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman  wrote:

> I think it's fine to include all of our PRs and issues in a github
> milestone, and we should do that, but I don't think that we want to include
> every single PR in our changelog.  When we have tried that in the past we
> have realized that it gets to be so much information that it's not useful.
> A good example of why is a new feature. If you are developing a new feature
> you could easily end up with 5 or more PRs: one to introduce the feature,
> one to add some more functionality, several to fix bugs with it, etc.
> Instead of having a line in the changelog for each one of those PRs, we
> should just have one line that says "introduced feature X" with maybe a
> blurb about what it is and any release notes that an operator would need to
> know.  This way the file in concise and easy to understand by anyone
> wanting to use a new version of our product.  I think it's also important
> to include what bug fixes (since the previous release) that we have fixed.
> Those are the reasons why I tend to lean towards a manual changelog.  It
> gives us the ability to control how much information goes into the
> changelog and the flexibility to make sure it is useful.
>
> On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell 
> wrote:
>
> > Why not leverage Github issues/milestones to determine the scope of each
> > release? Per our CONTRIBUTING.md
> >  > master/CONTRIBUTING.md>
> > :
> >
> > "If you have improvements (enhancements or bug fixes) for Traffic
> Control,
> > start by creating an issue
> > ..."
> >
> > That implies that all PR's should be mapped to an issue although we do
> not
> > enforce this but if we did it would be easy to put each issue into a
> > milestone (2.2 for example) and then pull a github report at any time.
> >
> > Orrather than creating an issue, put a good title/description on your
> > PR and then the PR can be assigned to the milestone instead.
> >
> > It just seems like that's what milestones are for so why not use them?
> >
> > Jeremy
> >
> >
> >
> > On Wed, Dec 13, 2017 at 3:28 PM, Dave Neuman  wrote:
> >
> > > I am +1 on this approach, I know it's manual and there could be
> conflicts
> > > and it's a bit of a PITA, but I think it actually has some benefits in
> > that
> > > a human can actually enter in important release notes that are readable
> > and
> > > make sense.
> > > That being said if someone is willing to make an automated approach
> work,
> > > that allows us to keep track of changes at a reasonable level (not per
> > > commit, not necessarily even per PR), then I could be +1 on that as
> well.
> > > I would need to someone volunteer to make it work before I give my +1
> > > though.
> > > Either way, we REALLY need a changelog that is updated regularly with
> > > important information.
> > >
> > > --Dave
> > >
> > > On Wed, Dec 13, 2017 at 3:00 PM, Steve Malenfant  >
> > > wrote:
> > >
> > > > Hey All,
> > > >
> > > > There has been a vote on not maintaining a CHANGELOG file in the past
> > and
> > > > seems like we leaned toward an automated process. I believe none of
> > them
> > > > had happened (please correct me if not).
> > > >
> > > > I have been upgrading Traffic Control from 2.1 to 2.2 this week and
> > found
> > > > numerous gotchas.
> > > >
> > > > Some examples of things I ran into and luckily I was able to get good
> > > > support from the Slack channels. Here is a few example of possible
> > > breaking
> > > > changes :
> > > >
> > > > - Delivery Service prefixes disappeared after upgrade, was not
> handled
> > in
> > > > postinstall (requires special attention, this was on this forum and
> > well
> > > > documented on the mailing list)
> > > > - Traffic Ops Golang doesn't connect to a Riak with self-signed
> > > > certificates
> > > > - Riak security grant needs updated
> > > > - cdn.conf configuration change
> > > > - Traffic Portal required for new features (URI Signing)
> > > > - cachekey plugin instead of cacheurl
> > > >
> > > > There was great enhancements made in 2.2 needs to be noticed by
> current
> > > and
> > > > new users.  If we 

Re: [VOTE] CHANGELOG.md file (second try)

[Dave Neuman]

I think it's fine to include all of our PRs and issues in a github
milestone, and we should do that, but I don't think that we want to include
every single PR in our changelog.  When we have tried that in the past we
have realized that it gets to be so much information that it's not useful.
A good example of why is a new feature. If you are developing a new feature
you could easily end up with 5 or more PRs: one to introduce the feature,
one to add some more functionality, several to fix bugs with it, etc.
Instead of having a line in the changelog for each one of those PRs, we
should just have one line that says "introduced feature X" with maybe a
blurb about what it is and any release notes that an operator would need to
know.  This way the file in concise and easy to understand by anyone
wanting to use a new version of our product.  I think it's also important
to include what bug fixes (since the previous release) that we have fixed.
Those are the reasons why I tend to lean towards a manual changelog.  It
gives us the ability to control how much information goes into the
changelog and the flexibility to make sure it is useful.

On Thu, Dec 14, 2017 at 8:13 AM, Jeremy Mitchell 
wrote:

> Why not leverage Github issues/milestones to determine the scope of each
> release? Per our CONTRIBUTING.md
>  master/CONTRIBUTING.md>
> :
>
> "If you have improvements (enhancements or bug fixes) for Traffic Control,
> start by creating an issue
> ..."
>
> That implies that all PR's should be mapped to an issue although we do not
> enforce this but if we did it would be easy to put each issue into a
> milestone (2.2 for example) and then pull a github report at any time.
>
> Orrather than creating an issue, put a good title/description on your
> PR and then the PR can be assigned to the milestone instead.
>
> It just seems like that's what milestones are for so why not use them?
>
> Jeremy
>
>
>
> On Wed, Dec 13, 2017 at 3:28 PM, Dave Neuman  wrote:
>
> > I am +1 on this approach, I know it's manual and there could be conflicts
> > and it's a bit of a PITA, but I think it actually has some benefits in
> that
> > a human can actually enter in important release notes that are readable
> and
> > make sense.
> > That being said if someone is willing to make an automated approach work,
> > that allows us to keep track of changes at a reasonable level (not per
> > commit, not necessarily even per PR), then I could be +1 on that as well.
> > I would need to someone volunteer to make it work before I give my +1
> > though.
> > Either way, we REALLY need a changelog that is updated regularly with
> > important information.
> >
> > --Dave
> >
> > On Wed, Dec 13, 2017 at 3:00 PM, Steve Malenfant 
> > wrote:
> >
> > > Hey All,
> > >
> > > There has been a vote on not maintaining a CHANGELOG file in the past
> and
> > > seems like we leaned toward an automated process. I believe none of
> them
> > > had happened (please correct me if not).
> > >
> > > I have been upgrading Traffic Control from 2.1 to 2.2 this week and
> found
> > > numerous gotchas.
> > >
> > > Some examples of things I ran into and luckily I was able to get good
> > > support from the Slack channels. Here is a few example of possible
> > breaking
> > > changes :
> > >
> > > - Delivery Service prefixes disappeared after upgrade, was not handled
> in
> > > postinstall (requires special attention, this was on this forum and
> well
> > > documented on the mailing list)
> > > - Traffic Ops Golang doesn't connect to a Riak with self-signed
> > > certificates
> > > - Riak security grant needs updated
> > > - cdn.conf configuration change
> > > - Traffic Portal required for new features (URI Signing)
> > > - cachekey plugin instead of cacheurl
> > >
> > > There was great enhancements made in 2.2 needs to be noticed by current
> > and
> > > new users.  If we are looking to get more engagement, that's probably
> the
> > > #1 thing to do. I usually go and read about all the other components
> > which
> > > we use around the Traffic Control CDN (Influx, Elastic, Grafana,
> etc...)
> > >
> > > So let me re-quote what Dave has sent and ask the same question again.
> > >
> > > ==
> > > Hey All,
> > > One thing we discussed at the meetup was the addition of a CHANGELOG.md
> > > file to the project.   This file will contain changes that are made to
> > the
> > > project including bug fixes and new features. (e.g.
> > > https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md).
> > Adding
> > > this file means that we will now require each PR to contain an update
> to
> > > the CHANGELOG.md file, and our documentation will need to be updated
> > > accordingly.
> > > I thought it would be good to open a vote for adding this file, and if
> it
> > > passes, I will update the documentation and 

Re: [VOTE] CHANGELOG.md file (second try)

[Jeremy Mitchell]

Why not leverage Github issues/milestones to determine the scope of each
release? Per our CONTRIBUTING.md

:

"If you have improvements (enhancements or bug fixes) for Traffic Control,
start by creating an issue
..."

That implies that all PR's should be mapped to an issue although we do not
enforce this but if we did it would be easy to put each issue into a
milestone (2.2 for example) and then pull a github report at any time.

Orrather than creating an issue, put a good title/description on your
PR and then the PR can be assigned to the milestone instead.

It just seems like that's what milestones are for so why not use them?

Jeremy



On Wed, Dec 13, 2017 at 3:28 PM, Dave Neuman  wrote:

> I am +1 on this approach, I know it's manual and there could be conflicts
> and it's a bit of a PITA, but I think it actually has some benefits in that
> a human can actually enter in important release notes that are readable and
> make sense.
> That being said if someone is willing to make an automated approach work,
> that allows us to keep track of changes at a reasonable level (not per
> commit, not necessarily even per PR), then I could be +1 on that as well.
> I would need to someone volunteer to make it work before I give my +1
> though.
> Either way, we REALLY need a changelog that is updated regularly with
> important information.
>
> --Dave
>
> On Wed, Dec 13, 2017 at 3:00 PM, Steve Malenfant 
> wrote:
>
> > Hey All,
> >
> > There has been a vote on not maintaining a CHANGELOG file in the past and
> > seems like we leaned toward an automated process. I believe none of them
> > had happened (please correct me if not).
> >
> > I have been upgrading Traffic Control from 2.1 to 2.2 this week and found
> > numerous gotchas.
> >
> > Some examples of things I ran into and luckily I was able to get good
> > support from the Slack channels. Here is a few example of possible
> breaking
> > changes :
> >
> > - Delivery Service prefixes disappeared after upgrade, was not handled in
> > postinstall (requires special attention, this was on this forum and well
> > documented on the mailing list)
> > - Traffic Ops Golang doesn't connect to a Riak with self-signed
> > certificates
> > - Riak security grant needs updated
> > - cdn.conf configuration change
> > - Traffic Portal required for new features (URI Signing)
> > - cachekey plugin instead of cacheurl
> >
> > There was great enhancements made in 2.2 needs to be noticed by current
> and
> > new users.  If we are looking to get more engagement, that's probably the
> > #1 thing to do. I usually go and read about all the other components
> which
> > we use around the Traffic Control CDN (Influx, Elastic, Grafana, etc...)
> >
> > So let me re-quote what Dave has sent and ask the same question again.
> >
> > ==
> > Hey All,
> > One thing we discussed at the meetup was the addition of a CHANGELOG.md
> > file to the project.   This file will contain changes that are made to
> the
> > project including bug fixes and new features. (e.g.
> > https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md).
> Adding
> > this file means that we will now require each PR to contain an update to
> > the CHANGELOG.md file, and our documentation will need to be updated
> > accordingly.
> > I thought it would be good to open a vote for adding this file, and if it
> > passes, I will update the documentation and add a CHANGELOG.md file.
> >
> > Thanks,
> > Dave
> > ==
> >
> > I'm a +1 on CHANGELOG, but I'm not heavy creating PRs which kind
> influence
> > my vote.
> >
> > Steve
> >
>