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

[Rawlin Peters <ra...@gmail.com>]

Hey all,

So it appears this vote passed in favor of adding a CHANGELOG.md file
without having a changelog label in GitHub. Is anyone currently
working on one?

With the 2.2 release planned for 2/12/18, I'd like to at least put in
some upgrade release notes about Per-Delivery-Service Routing Names.
If no one has a CHANGELOG.md in progress, I'll take the liberty to
start one and add those release notes in there (using
https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
example template).

-Rawlin

On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com> wrote:
> [X] +1 to adding a changelog.MD file
> [] -1 to adding a changelog.MD file
>
> That said, I'm only in favour of it if we're fastidious about
> requiring changelog updates on every single PR. A PR should either
> provide a reasonable changelog entry, or, in the body of the PR,
> justify it's absence. A simple "This bugfix does not require a
> changelog entry." is sufficient for trivial bugfixes. That's plenty
> for a reviewer to quickly either agree or decide to request (or
> provide) an entry.
>
> If we add the changelog file, we need to update the contributing file
> to include the new guidelines.
>
> On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <mi...@gmail.com> wrote:
>> Yes, I was about to mention milestones. Why not leverage Github milestones
>> on issues/PRs? We talked about using milestones at the last TC summit to
>> determine the scope of a release. Now is our chance to do that.
>>
>> Milestones can be applied to issues or PRs. I tend to create issues for
>> everything I do, so I would put the milestone on the issue but others can
>> simply put a milestone on their PR (if there is no related issue). Either
>> way, it tags the items we want included in the changelog. And then the RM
>> can build the changelog from the milestones. Easy peasy.
>>
>> Jeremy
>>
>>
>>
>>
>>
>>
>> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org> wrote:
>>
>>>
>>>
>>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org> wrote:
>>> >
>>> > Looks like this thread died over the holidays.  Let me try to bring it
>>> back
>>> > up before we cut a 2.2 branch.
>>> > Can you please respond with *just* the following:
>>> >
>>> > [X] +1 to adding a changelog.MD file
>>> > [] -1 to adding a changelog.MD file
>>> >
>>> > [] +1 to adding a changelog label in github
>>> > [X] -1 to adding a changelog label in github
>>> >
>>>
>>>
>>> To add to the previous thread / thoughts. I feel reasonably strongly that
>>> having a changelog label in Github is not useful. In the ATS community, we
>>> can *barely* get people to set the Milestone properly, and I feel that the
>>> Milestone is a much more important thing to keep accurate than anything
>>> else. And, to be normalized, you don’t want to duplicate this info :-).
>>>
>>> So, what we do is have the RM be like a hawk over the Milestones, and then
>>> run Phil’s fancy pants script to generate the ChangeLog from the Milestones
>>> on all PRs closed.
>>>
>>> Cheers,
>>>
>>> — leif
>>>
>>> > Thanks,
>>> > Dave
>>> >
>>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <de...@gmail.com>
>>> > wrote:
>>> >
>>> >> +1 on the CHANGELOG.md as well, but I like having the changelog label
>>> >> because it helps streamline it's creation.  I also think the labels are
>>> >> valuable because they help summarize the parts of the repo that changed
>>> and
>>> >> keeps the concept closer to the repository (where the real change is).
>>> >>
>>> >> -Dew
>>> >>
>>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <robert.o.butts@gmail.com
>>> >
>>> >> 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 <ne...@apache.org>
>>> 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 <
>>> >> mitchell852@gmail.com>
>>> >>>> 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 <
>>> >> dewrich@gmail.com
>>> >>>>
>>> >>>>> 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_Gelinas@comcast.com>
>>> >>>>>> wrote:
>>> >>>>>>
>>> >>>>>>> I'm +1 for the label as well.
>>> >>>>>>>
>>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>>> >>>> robert.o.butts@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 <
>>> >>>>>> dewrich@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 <
>>> >>>>>>> mitchell852@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 <
>>> >>> neuman@apache.org
>>> >>>>>
>>> >>>>>>> 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 <
>>> >>>>>>>>> mitchell852@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 <
>>> >>>> neuman@apache.org>
>>> >>>>>>>>>> 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 <
>>> >>>>>>>>>>> mitchell852@gmail.com>
>>> >>>>>>>>>>>>> wrote:
>>> >>>>>>>>>>>>>
>>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to determine
>>> >> the
>>> >>>>> scope
>>> >>>>>>>>> of
>>> >>>>>>>>>>>> each
>>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>>> >>>>>>>>>>>>>> <https://github.com/apache/
>>> >> incubator-trafficcontrol/blob/
>>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>>> >>>>>>>>>>>>>> :
>>> >>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug fixes) for
>>> >>>>> Traffic
>>> >>>>>>>>>>>>> Control,
>>> >>>>>>>>>>>>>> start by creating an issue
>>> >>>>>>>>>>>>>> <https://github.com/apache/incubator-trafficcontrol/
>>> >> issues
>>> >>>>>> ..."
>>> >>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>> 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.
>>> >>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>> Or....rather 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 <
>>> >>>>> neuman@apache.org>
>>> >>>>>>>>>>>> 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 <
>>> >>>>>>>>>>>> smalenfant@gmail.com
>>> >>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>>> 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
>>> >>>>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>>
>>> >>>>>>>>>>>>>
>>> >>>>>>>>>>>>
>>> >>>>>>>>>>>
>>> >>>>>>>>>>
>>> >>>>>>>>>
>>> >>>>>>>
>>> >>>>>>
>>> >>>>>
>>> >>>>
>>> >>>
>>> >>
>>>
>>>

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

[Dewayne Richardson <de...@apache.org>]

+1

On Tue, Feb 27, 2018 at 10:18 PM, Dan Kirkwood <da...@gmail.com> wrote:

> +1
>
> On Tue, Feb 27, 2018 at 2:50 PM, Jeremy Mitchell <mi...@gmail.com>
> wrote:
>
> > I like that format. Bullets seems nice and simple with external links
> where
> > more info is required.
> >
> > I would be in favor of a PR to add these sections so it's easy for the
> next
> > person to add a bullet to the relevant section.
> >
> > On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
> > wrote:
> >
> > > Hey folks,
> > >
> > > So I used the influxdb changelog as an example format, but @dew has
> > > shown me this popular project for changelog convention:
> > > http://keepachangelog.com/en/1.0.0/. For example see the project
> > > changelog: https://github.com/olivierlacan/keep-a-changelog/
> > > blob/master/CHANGELOG.md.
> > >
> > > Since we now have a changelog, it would be best to have a standard,
> > > agreed-upon format for it so that we can keep it consistent for every
> > > release.
> > >
> > > Basically it means every release has its own section (with an
> > > "unreleased" section at the top), and everything will be
> > > bullet-pointed underneath one of these sections for every release:
> > > - "Added" for new features.
> > > - "Changed" for changes in existing functionality.
> > > - "Deprecated" for soon-to-be removed features.
> > > - "Removed" for now removed features.
> > > - "Fixed" for any bug fixes.
> > > - "Security" in case of vulnerabilities.
> > >
> > > For example with my per-DS routing name upgrade notes currently in the
> > > changelog, I would add that to the "Added" section and link to the
> > > upgrade notes in our docs.
> > >
> > >  What do you all think? All in favor of accepting this keepachangelog
> > > format?
> > >
> > > - Rawlin
> > >
> > >
> > >
> > > On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <rawlin.peters@gmail.com
> >
> > > wrote:
> > > > I went ahead and created one:
> > > > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> > > > review and merge if you are okay with the current format. I'm not
> sure
> > > > if we want to go back and add a list of all the new features in 2.2
> or
> > > > not, but please add to the CHANGELOG.md file if you have any pending
> > > > release notes like 2.2 upgrade gotchas you'd like to get in.
> > > >
> > > > Thanks,
> > > > Rawlin
> > > >
> > > > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org>
> wrote:
> > > >> Hey Rawlin,
> > > >> I think Steve was starting to work on one, so we will see what he
> > says.
> > > >> If he doesn't have one started, I think you can go ahead and create
> > one.
> > > >>
> > > >> Thanks,
> > > >> Dave
> > > >>
> > > >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <
> > rawlin.peters@gmail.com>
> > > >> wrote:
> > > >>
> > > >>> Hey all,
> > > >>>
> > > >>> So it appears this vote passed in favor of adding a CHANGELOG.md
> file
> > > >>> without having a changelog label in GitHub. Is anyone currently
> > > >>> working on one?
> > > >>>
> > > >>> With the 2.2 release planned for 2/12/18, I'd like to at least put
> in
> > > >>> some upgrade release notes about Per-Delivery-Service Routing
> Names.
> > > >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> > > >>> start one and add those release notes in there (using
> > > >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as
> > an
> > > >>> example template).
> > > >>>
> > > >>> -Rawlin
> > > >>>
> > > >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <
> alficles@gmail.com>
> > > >>> wrote:
> > > >>> > [X] +1 to adding a changelog.MD file
> > > >>> > [] -1 to adding a changelog.MD file
> > > >>> >
> > > >>> > That said, I'm only in favour of it if we're fastidious about
> > > >>> > requiring changelog updates on every single PR. A PR should
> either
> > > >>> > provide a reasonable changelog entry, or, in the body of the PR,
> > > >>> > justify it's absence. A simple "This bugfix does not require a
> > > >>> > changelog entry." is sufficient for trivial bugfixes. That's
> plenty
> > > >>> > for a reviewer to quickly either agree or decide to request (or
> > > >>> > provide) an entry.
> > > >>> >
> > > >>> > If we add the changelog file, we need to update the contributing
> > file
> > > >>> > to include the new guidelines.
> > > >>> >
> > > >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
> > > mitchell852@gmail.com>
> > > >>> wrote:
> > > >>> >> Yes, I was about to mention milestones. Why not leverage Github
> > > >>> milestones
> > > >>> >> on issues/PRs? We talked about using milestones at the last TC
> > > summit to
> > > >>> >> determine the scope of a release. Now is our chance to do that.
> > > >>> >>
> > > >>> >> Milestones can be applied to issues or PRs. I tend to create
> > issues
> > > for
> > > >>> >> everything I do, so I would put the milestone on the issue but
> > > others
> > > >>> can
> > > >>> >> simply put a milestone on their PR (if there is no related
> issue).
> > > >>> Either
> > > >>> >> way, it tags the items we want included in the changelog. And
> then
> > > the
> > > >>> RM
> > > >>> >> can build the changelog from the milestones. Easy peasy.
> > > >>> >>
> > > >>> >> Jeremy
> > > >>> >>
> > > >>> >>
> > > >>> >>
> > > >>> >>
> > > >>> >>
> > > >>> >>
> > > >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zwoop@apache.org
> >
> > > wrote:
> > > >>> >>
> > > >>> >>>
> > > >>> >>>
> > > >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
> > > wrote:
> > > >>> >>> >
> > > >>> >>> > Looks like this thread died over the holidays.  Let me try to
> > > bring
> > > >>> it
> > > >>> >>> back
> > > >>> >>> > up before we cut a 2.2 branch.
> > > >>> >>> > Can you please respond with *just* the following:
> > > >>> >>> >
> > > >>> >>> > [X] +1 to adding a changelog.MD file
> > > >>> >>> > [] -1 to adding a changelog.MD file
> > > >>> >>> >
> > > >>> >>> > [] +1 to adding a changelog label in github
> > > >>> >>> > [X] -1 to adding a changelog label in github
> > > >>> >>> >
> > > >>> >>>
> > > >>> >>>
> > > >>> >>> To add to the previous thread / thoughts. I feel reasonably
> > > strongly
> > > >>> that
> > > >>> >>> having a changelog label in Github is not useful. In the ATS
> > > >>> community, we
> > > >>> >>> can *barely* get people to set the Milestone properly, and I
> feel
> > > that
> > > >>> the
> > > >>> >>> Milestone is a much more important thing to keep accurate than
> > > anything
> > > >>> >>> else. And, to be normalized, you don’t want to duplicate this
> > info
> > > :-).
> > > >>> >>>
> > > >>> >>> So, what we do is have the RM be like a hawk over the
> Milestones,
> > > and
> > > >>> then
> > > >>> >>> run Phil’s fancy pants script to generate the ChangeLog from
> the
> > > >>> Milestones
> > > >>> >>> on all PRs closed.
> > > >>> >>>
> > > >>> >>> Cheers,
> > > >>> >>>
> > > >>> >>> — leif
> > > >>> >>>
> > > >>> >>> > Thanks,
> > > >>> >>> > Dave
> > > >>> >>> >
> > > >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> > > >>> dewrich@gmail.com>
> > > >>> >>> > wrote:
> > > >>> >>> >
> > > >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the
> > changelog
> > > >>> label
> > > >>> >>> >> because it helps streamline it's creation.  I also think the
> > > labels
> > > >>> are
> > > >>> >>> >> valuable because they help summarize the parts of the repo
> > that
> > > >>> changed
> > > >>> >>> and
> > > >>> >>> >> keeps the concept closer to the repository (where the real
> > > change
> > > >>> is).
> > > >>> >>> >>
> > > >>> >>> >> -Dew
> > > >>> >>> >>
> > > >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> > > >>> robert.o.butts@gmail.com
> > > >>> >>> >
> > > >>> >>> >> 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 <
> > > neuman@apache.org>
> > > >>> >>> 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 <
> > > >>> >>> >> mitchell852@gmail.com>
> > > >>> >>> >>>> 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 <
> > > >>> >>> >> dewrich@gmail.com
> > > >>> >>> >>>>
> > > >>> >>> >>>>> 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_Gelinas@comcast.com>
> > > >>> >>> >>>>>> wrote:
> > > >>> >>> >>>>>>
> > > >>> >>> >>>>>>> I'm +1 for the label as well.
> > > >>> >>> >>>>>>>
> > > >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> > > >>> >>> >>>> robert.o.butts@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 <
> > > >>> >>> >>>>>> dewrich@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 <
> > > >>> >>> >>>>>>> mitchell852@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 <
> > > >>> >>> >>> neuman@apache.org
> > > >>> >>> >>>>>
> > > >>> >>> >>>>>>> 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 <
> > > >>> >>> >>>>>>>>> mitchell852@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 <
> > > >>> >>> >>>> neuman@apache.org>
> > > >>> >>> >>>>>>>>>> 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
> <
> > > >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
> > > >>> >>> >>>>>>>>>>>>> wrote:
> > > >>> >>> >>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
> > > determine
> > > >>> >>> >> the
> > > >>> >>> >>>>> scope
> > > >>> >>> >>>>>>>>> of
> > > >>> >>> >>>>>>>>>>>> each
> > > >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> > > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > > >>> >>> >> incubator-trafficcontrol/blob/
> > > >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> > > >>> >>> >>>>>>>>>>>>>> :
> > > >>> >>> >>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
> > > fixes)
> > > >>> for
> > > >>> >>> >>>>> Traffic
> > > >>> >>> >>>>>>>>>>>>> Control,
> > > >>> >>> >>>>>>>>>>>>>> start by creating an issue
> > > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > > incubator-trafficcontrol/
> > > >>> >>> >> issues
> > > >>> >>> >>>>>> ..."
> > > >>> >>> >>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>> 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.
> > > >>> >>> >>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
> > > >>> >>> >>>>> neuman@apache.org>
> > > >>> >>> >>>>>>>>>>>> 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
> > <
> > > >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
> > > >>> >>> >>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>>> 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
> > > >>> >>> >>>>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>>
> > > >>> >>> >>>>>>>>>>
> > > >>> >>> >>>>>>>>>
> > > >>> >>> >>>>>>>
> > > >>> >>> >>>>>>
> > > >>> >>> >>>>>
> > > >>> >>> >>>>
> > > >>> >>> >>>
> > > >>> >>> >>
> > > >>> >>>
> > > >>> >>>
> > > >>>
> > >
> >
>

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

[Dan Kirkwood <da...@gmail.com>]

+1

On Tue, Feb 27, 2018 at 2:50 PM, Jeremy Mitchell <mi...@gmail.com>
wrote:

> I like that format. Bullets seems nice and simple with external links where
> more info is required.
>
> I would be in favor of a PR to add these sections so it's easy for the next
> person to add a bullet to the relevant section.
>
> On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
>
> > Hey folks,
> >
> > So I used the influxdb changelog as an example format, but @dew has
> > shown me this popular project for changelog convention:
> > http://keepachangelog.com/en/1.0.0/. For example see the project
> > changelog: https://github.com/olivierlacan/keep-a-changelog/
> > blob/master/CHANGELOG.md.
> >
> > Since we now have a changelog, it would be best to have a standard,
> > agreed-upon format for it so that we can keep it consistent for every
> > release.
> >
> > Basically it means every release has its own section (with an
> > "unreleased" section at the top), and everything will be
> > bullet-pointed underneath one of these sections for every release:
> > - "Added" for new features.
> > - "Changed" for changes in existing functionality.
> > - "Deprecated" for soon-to-be removed features.
> > - "Removed" for now removed features.
> > - "Fixed" for any bug fixes.
> > - "Security" in case of vulnerabilities.
> >
> > For example with my per-DS routing name upgrade notes currently in the
> > changelog, I would add that to the "Added" section and link to the
> > upgrade notes in our docs.
> >
> >  What do you all think? All in favor of accepting this keepachangelog
> > format?
> >
> > - Rawlin
> >
> >
> >
> > On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
> > wrote:
> > > I went ahead and created one:
> > > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> > > review and merge if you are okay with the current format. I'm not sure
> > > if we want to go back and add a list of all the new features in 2.2 or
> > > not, but please add to the CHANGELOG.md file if you have any pending
> > > release notes like 2.2 upgrade gotchas you'd like to get in.
> > >
> > > Thanks,
> > > Rawlin
> > >
> > > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
> > >> Hey Rawlin,
> > >> I think Steve was starting to work on one, so we will see what he
> says.
> > >> If he doesn't have one started, I think you can go ahead and create
> one.
> > >>
> > >> Thanks,
> > >> Dave
> > >>
> > >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <
> rawlin.peters@gmail.com>
> > >> wrote:
> > >>
> > >>> Hey all,
> > >>>
> > >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
> > >>> without having a changelog label in GitHub. Is anyone currently
> > >>> working on one?
> > >>>
> > >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
> > >>> some upgrade release notes about Per-Delivery-Service Routing Names.
> > >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> > >>> start one and add those release notes in there (using
> > >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as
> an
> > >>> example template).
> > >>>
> > >>> -Rawlin
> > >>>
> > >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
> > >>> wrote:
> > >>> > [X] +1 to adding a changelog.MD file
> > >>> > [] -1 to adding a changelog.MD file
> > >>> >
> > >>> > That said, I'm only in favour of it if we're fastidious about
> > >>> > requiring changelog updates on every single PR. A PR should either
> > >>> > provide a reasonable changelog entry, or, in the body of the PR,
> > >>> > justify it's absence. A simple "This bugfix does not require a
> > >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
> > >>> > for a reviewer to quickly either agree or decide to request (or
> > >>> > provide) an entry.
> > >>> >
> > >>> > If we add the changelog file, we need to update the contributing
> file
> > >>> > to include the new guidelines.
> > >>> >
> > >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
> > mitchell852@gmail.com>
> > >>> wrote:
> > >>> >> Yes, I was about to mention milestones. Why not leverage Github
> > >>> milestones
> > >>> >> on issues/PRs? We talked about using milestones at the last TC
> > summit to
> > >>> >> determine the scope of a release. Now is our chance to do that.
> > >>> >>
> > >>> >> Milestones can be applied to issues or PRs. I tend to create
> issues
> > for
> > >>> >> everything I do, so I would put the milestone on the issue but
> > others
> > >>> can
> > >>> >> simply put a milestone on their PR (if there is no related issue).
> > >>> Either
> > >>> >> way, it tags the items we want included in the changelog. And then
> > the
> > >>> RM
> > >>> >> can build the changelog from the milestones. Easy peasy.
> > >>> >>
> > >>> >> Jeremy
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
> > wrote:
> > >>> >>
> > >>> >>>
> > >>> >>>
> > >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
> > wrote:
> > >>> >>> >
> > >>> >>> > Looks like this thread died over the holidays.  Let me try to
> > bring
> > >>> it
> > >>> >>> back
> > >>> >>> > up before we cut a 2.2 branch.
> > >>> >>> > Can you please respond with *just* the following:
> > >>> >>> >
> > >>> >>> > [X] +1 to adding a changelog.MD file
> > >>> >>> > [] -1 to adding a changelog.MD file
> > >>> >>> >
> > >>> >>> > [] +1 to adding a changelog label in github
> > >>> >>> > [X] -1 to adding a changelog label in github
> > >>> >>> >
> > >>> >>>
> > >>> >>>
> > >>> >>> To add to the previous thread / thoughts. I feel reasonably
> > strongly
> > >>> that
> > >>> >>> having a changelog label in Github is not useful. In the ATS
> > >>> community, we
> > >>> >>> can *barely* get people to set the Milestone properly, and I feel
> > that
> > >>> the
> > >>> >>> Milestone is a much more important thing to keep accurate than
> > anything
> > >>> >>> else. And, to be normalized, you don’t want to duplicate this
> info
> > :-).
> > >>> >>>
> > >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
> > and
> > >>> then
> > >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
> > >>> Milestones
> > >>> >>> on all PRs closed.
> > >>> >>>
> > >>> >>> Cheers,
> > >>> >>>
> > >>> >>> — leif
> > >>> >>>
> > >>> >>> > Thanks,
> > >>> >>> > Dave
> > >>> >>> >
> > >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> > >>> dewrich@gmail.com>
> > >>> >>> > wrote:
> > >>> >>> >
> > >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the
> changelog
> > >>> label
> > >>> >>> >> because it helps streamline it's creation.  I also think the
> > labels
> > >>> are
> > >>> >>> >> valuable because they help summarize the parts of the repo
> that
> > >>> changed
> > >>> >>> and
> > >>> >>> >> keeps the concept closer to the repository (where the real
> > change
> > >>> is).
> > >>> >>> >>
> > >>> >>> >> -Dew
> > >>> >>> >>
> > >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> > >>> robert.o.butts@gmail.com
> > >>> >>> >
> > >>> >>> >> 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 <
> > neuman@apache.org>
> > >>> >>> 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 <
> > >>> >>> >> mitchell852@gmail.com>
> > >>> >>> >>>> 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 <
> > >>> >>> >> dewrich@gmail.com
> > >>> >>> >>>>
> > >>> >>> >>>>> 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_Gelinas@comcast.com>
> > >>> >>> >>>>>> wrote:
> > >>> >>> >>>>>>
> > >>> >>> >>>>>>> I'm +1 for the label as well.
> > >>> >>> >>>>>>>
> > >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> > >>> >>> >>>> robert.o.butts@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 <
> > >>> >>> >>>>>> dewrich@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 <
> > >>> >>> >>>>>>> mitchell852@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 <
> > >>> >>> >>> neuman@apache.org
> > >>> >>> >>>>>
> > >>> >>> >>>>>>> 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 <
> > >>> >>> >>>>>>>>> mitchell852@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 <
> > >>> >>> >>>> neuman@apache.org>
> > >>> >>> >>>>>>>>>> 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 <
> > >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
> > >>> >>> >>>>>>>>>>>>> wrote:
> > >>> >>> >>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
> > determine
> > >>> >>> >> the
> > >>> >>> >>>>> scope
> > >>> >>> >>>>>>>>> of
> > >>> >>> >>>>>>>>>>>> each
> > >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > >>> >>> >> incubator-trafficcontrol/blob/
> > >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> > >>> >>> >>>>>>>>>>>>>> :
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
> > fixes)
> > >>> for
> > >>> >>> >>>>> Traffic
> > >>> >>> >>>>>>>>>>>>> Control,
> > >>> >>> >>>>>>>>>>>>>> start by creating an issue
> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > incubator-trafficcontrol/
> > >>> >>> >> issues
> > >>> >>> >>>>>> ..."
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> 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.
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
> > >>> >>> >>>>> neuman@apache.org>
> > >>> >>> >>>>>>>>>>>> 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
> <
> > >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>> 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
> > >>> >>> >>>>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>
> > >>> >>> >>>>>>>>>>
> > >>> >>> >>>>>>>>>
> > >>> >>> >>>>>>>
> > >>> >>> >>>>>>
> > >>> >>> >>>>>
> > >>> >>> >>>>
> > >>> >>> >>>
> > >>> >>> >>
> > >>> >>>
> > >>> >>>
> > >>>
> >
>

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

[Chris Lemmons <al...@gmail.com>]

The keepachangelog folks seem to have done a great job describing a
way that works. I'm +1 on re-using their work. :)

On Tue, Feb 27, 2018 at 8:27 PM, Dave Neuman <ne...@apache.org> wrote:
> +1
>
> On Tue, Feb 27, 2018 at 14:50 Jeremy Mitchell <mi...@gmail.com> wrote:
>
>> I like that format. Bullets seems nice and simple with external links where
>> more info is required.
>>
>> I would be in favor of a PR to add these sections so it's easy for the next
>> person to add a bullet to the relevant section.
>>
>> On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
>> wrote:
>>
>> > Hey folks,
>> >
>> > So I used the influxdb changelog as an example format, but @dew has
>> > shown me this popular project for changelog convention:
>> > http://keepachangelog.com/en/1.0.0/. For example see the project
>> > changelog: https://github.com/olivierlacan/keep-a-changelog/
>> > blob/master/CHANGELOG.md.
>> >
>> > Since we now have a changelog, it would be best to have a standard,
>> > agreed-upon format for it so that we can keep it consistent for every
>> > release.
>> >
>> > Basically it means every release has its own section (with an
>> > "unreleased" section at the top), and everything will be
>> > bullet-pointed underneath one of these sections for every release:
>> > - "Added" for new features.
>> > - "Changed" for changes in existing functionality.
>> > - "Deprecated" for soon-to-be removed features.
>> > - "Removed" for now removed features.
>> > - "Fixed" for any bug fixes.
>> > - "Security" in case of vulnerabilities.
>> >
>> > For example with my per-DS routing name upgrade notes currently in the
>> > changelog, I would add that to the "Added" section and link to the
>> > upgrade notes in our docs.
>> >
>> >  What do you all think? All in favor of accepting this keepachangelog
>> > format?
>> >
>> > - Rawlin
>> >
>> >
>> >
>> > On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
>> > wrote:
>> > > I went ahead and created one:
>> > > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
>> > > review and merge if you are okay with the current format. I'm not sure
>> > > if we want to go back and add a list of all the new features in 2.2 or
>> > > not, but please add to the CHANGELOG.md file if you have any pending
>> > > release notes like 2.2 upgrade gotchas you'd like to get in.
>> > >
>> > > Thanks,
>> > > Rawlin
>> > >
>> > > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
>> > >> Hey Rawlin,
>> > >> I think Steve was starting to work on one, so we will see what he
>> says.
>> > >> If he doesn't have one started, I think you can go ahead and create
>> one.
>> > >>
>> > >> Thanks,
>> > >> Dave
>> > >>
>> > >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <
>> rawlin.peters@gmail.com>
>> > >> wrote:
>> > >>
>> > >>> Hey all,
>> > >>>
>> > >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
>> > >>> without having a changelog label in GitHub. Is anyone currently
>> > >>> working on one?
>> > >>>
>> > >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
>> > >>> some upgrade release notes about Per-Delivery-Service Routing Names.
>> > >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
>> > >>> start one and add those release notes in there (using
>> > >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as
>> an
>> > >>> example template).
>> > >>>
>> > >>> -Rawlin
>> > >>>
>> > >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
>> > >>> wrote:
>> > >>> > [X] +1 to adding a changelog.MD file
>> > >>> > [] -1 to adding a changelog.MD file
>> > >>> >
>> > >>> > That said, I'm only in favour of it if we're fastidious about
>> > >>> > requiring changelog updates on every single PR. A PR should either
>> > >>> > provide a reasonable changelog entry, or, in the body of the PR,
>> > >>> > justify it's absence. A simple "This bugfix does not require a
>> > >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
>> > >>> > for a reviewer to quickly either agree or decide to request (or
>> > >>> > provide) an entry.
>> > >>> >
>> > >>> > If we add the changelog file, we need to update the contributing
>> file
>> > >>> > to include the new guidelines.
>> > >>> >
>> > >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
>> > mitchell852@gmail.com>
>> > >>> wrote:
>> > >>> >> Yes, I was about to mention milestones. Why not leverage Github
>> > >>> milestones
>> > >>> >> on issues/PRs? We talked about using milestones at the last TC
>> > summit to
>> > >>> >> determine the scope of a release. Now is our chance to do that.
>> > >>> >>
>> > >>> >> Milestones can be applied to issues or PRs. I tend to create
>> issues
>> > for
>> > >>> >> everything I do, so I would put the milestone on the issue but
>> > others
>> > >>> can
>> > >>> >> simply put a milestone on their PR (if there is no related issue).
>> > >>> Either
>> > >>> >> way, it tags the items we want included in the changelog. And then
>> > the
>> > >>> RM
>> > >>> >> can build the changelog from the milestones. Easy peasy.
>> > >>> >>
>> > >>> >> Jeremy
>> > >>> >>
>> > >>> >>
>> > >>> >>
>> > >>> >>
>> > >>> >>
>> > >>> >>
>> > >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
>> > wrote:
>> > >>> >>
>> > >>> >>>
>> > >>> >>>
>> > >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
>> > wrote:
>> > >>> >>> >
>> > >>> >>> > Looks like this thread died over the holidays.  Let me try to
>> > bring
>> > >>> it
>> > >>> >>> back
>> > >>> >>> > up before we cut a 2.2 branch.
>> > >>> >>> > Can you please respond with *just* the following:
>> > >>> >>> >
>> > >>> >>> > [X] +1 to adding a changelog.MD file
>> > >>> >>> > [] -1 to adding a changelog.MD file
>> > >>> >>> >
>> > >>> >>> > [] +1 to adding a changelog label in github
>> > >>> >>> > [X] -1 to adding a changelog label in github
>> > >>> >>> >
>> > >>> >>>
>> > >>> >>>
>> > >>> >>> To add to the previous thread / thoughts. I feel reasonably
>> > strongly
>> > >>> that
>> > >>> >>> having a changelog label in Github is not useful. In the ATS
>> > >>> community, we
>> > >>> >>> can *barely* get people to set the Milestone properly, and I feel
>> > that
>> > >>> the
>> > >>> >>> Milestone is a much more important thing to keep accurate than
>> > anything
>> > >>> >>> else. And, to be normalized, you don’t want to duplicate this
>> info
>> > :-).
>> > >>> >>>
>> > >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
>> > and
>> > >>> then
>> > >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
>> > >>> Milestones
>> > >>> >>> on all PRs closed.
>> > >>> >>>
>> > >>> >>> Cheers,
>> > >>> >>>
>> > >>> >>> — leif
>> > >>> >>>
>> > >>> >>> > Thanks,
>> > >>> >>> > Dave
>> > >>> >>> >
>> > >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
>> > >>> dewrich@gmail.com>
>> > >>> >>> > wrote:
>> > >>> >>> >
>> > >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the
>> changelog
>> > >>> label
>> > >>> >>> >> because it helps streamline it's creation.  I also think the
>> > labels
>> > >>> are
>> > >>> >>> >> valuable because they help summarize the parts of the repo
>> that
>> > >>> changed
>> > >>> >>> and
>> > >>> >>> >> keeps the concept closer to the repository (where the real
>> > change
>> > >>> is).
>> > >>> >>> >>
>> > >>> >>> >> -Dew
>> > >>> >>> >>
>> > >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
>> > >>> robert.o.butts@gmail.com
>> > >>> >>> >
>> > >>> >>> >> 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 <
>> > neuman@apache.org>
>> > >>> >>> 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 <
>> > >>> >>> >> mitchell852@gmail.com>
>> > >>> >>> >>>> 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 <
>> > >>> >>> >> dewrich@gmail.com
>> > >>> >>> >>>>
>> > >>> >>> >>>>> 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_Gelinas@comcast.com>
>> > >>> >>> >>>>>> wrote:
>> > >>> >>> >>>>>>
>> > >>> >>> >>>>>>> I'm +1 for the label as well.
>> > >>> >>> >>>>>>>
>> > >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>> > >>> >>> >>>> robert.o.butts@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 <
>> > >>> >>> >>>>>> dewrich@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 <
>> > >>> >>> >>>>>>> mitchell852@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 <
>> > >>> >>> >>> neuman@apache.org
>> > >>> >>> >>>>>
>> > >>> >>> >>>>>>> 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 <
>> > >>> >>> >>>>>>>>> mitchell852@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 <
>> > >>> >>> >>>> neuman@apache.org>
>> > >>> >>> >>>>>>>>>> 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 <
>> > >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
>> > >>> >>> >>>>>>>>>>>>> wrote:
>> > >>> >>> >>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
>> > determine
>> > >>> >>> >> the
>> > >>> >>> >>>>> scope
>> > >>> >>> >>>>>>>>> of
>> > >>> >>> >>>>>>>>>>>> each
>> > >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>> > >>> >>> >> incubator-trafficcontrol/blob/
>> > >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>> > >>> >>> >>>>>>>>>>>>>> :
>> > >>> >>> >>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
>> > fixes)
>> > >>> for
>> > >>> >>> >>>>> Traffic
>> > >>> >>> >>>>>>>>>>>>> Control,
>> > >>> >>> >>>>>>>>>>>>>> start by creating an issue
>> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>> > incubator-trafficcontrol/
>> > >>> >>> >> issues
>> > >>> >>> >>>>>> ..."
>> > >>> >>> >>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>> 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.
>> > >>> >>> >>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
>> > >>> >>> >>>>> neuman@apache.org>
>> > >>> >>> >>>>>>>>>>>> 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
>> <
>> > >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
>> > >>> >>> >>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>>> 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
>> > >>> >>> >>>>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>>
>> > >>> >>> >>>>>>>>>>
>> > >>> >>> >>>>>>>>>
>> > >>> >>> >>>>>>>
>> > >>> >>> >>>>>>
>> > >>> >>> >>>>>
>> > >>> >>> >>>>
>> > >>> >>> >>>
>> > >>> >>> >>
>> > >>> >>>
>> > >>> >>>
>> > >>>
>> >
>>

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

[Dave Neuman <ne...@apache.org>]

+1

On Tue, Feb 27, 2018 at 14:50 Jeremy Mitchell <mi...@gmail.com> wrote:

> I like that format. Bullets seems nice and simple with external links where
> more info is required.
>
> I would be in favor of a PR to add these sections so it's easy for the next
> person to add a bullet to the relevant section.
>
> On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
>
> > Hey folks,
> >
> > So I used the influxdb changelog as an example format, but @dew has
> > shown me this popular project for changelog convention:
> > http://keepachangelog.com/en/1.0.0/. For example see the project
> > changelog: https://github.com/olivierlacan/keep-a-changelog/
> > blob/master/CHANGELOG.md.
> >
> > Since we now have a changelog, it would be best to have a standard,
> > agreed-upon format for it so that we can keep it consistent for every
> > release.
> >
> > Basically it means every release has its own section (with an
> > "unreleased" section at the top), and everything will be
> > bullet-pointed underneath one of these sections for every release:
> > - "Added" for new features.
> > - "Changed" for changes in existing functionality.
> > - "Deprecated" for soon-to-be removed features.
> > - "Removed" for now removed features.
> > - "Fixed" for any bug fixes.
> > - "Security" in case of vulnerabilities.
> >
> > For example with my per-DS routing name upgrade notes currently in the
> > changelog, I would add that to the "Added" section and link to the
> > upgrade notes in our docs.
> >
> >  What do you all think? All in favor of accepting this keepachangelog
> > format?
> >
> > - Rawlin
> >
> >
> >
> > On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
> > wrote:
> > > I went ahead and created one:
> > > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> > > review and merge if you are okay with the current format. I'm not sure
> > > if we want to go back and add a list of all the new features in 2.2 or
> > > not, but please add to the CHANGELOG.md file if you have any pending
> > > release notes like 2.2 upgrade gotchas you'd like to get in.
> > >
> > > Thanks,
> > > Rawlin
> > >
> > > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
> > >> Hey Rawlin,
> > >> I think Steve was starting to work on one, so we will see what he
> says.
> > >> If he doesn't have one started, I think you can go ahead and create
> one.
> > >>
> > >> Thanks,
> > >> Dave
> > >>
> > >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <
> rawlin.peters@gmail.com>
> > >> wrote:
> > >>
> > >>> Hey all,
> > >>>
> > >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
> > >>> without having a changelog label in GitHub. Is anyone currently
> > >>> working on one?
> > >>>
> > >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
> > >>> some upgrade release notes about Per-Delivery-Service Routing Names.
> > >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> > >>> start one and add those release notes in there (using
> > >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as
> an
> > >>> example template).
> > >>>
> > >>> -Rawlin
> > >>>
> > >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
> > >>> wrote:
> > >>> > [X] +1 to adding a changelog.MD file
> > >>> > [] -1 to adding a changelog.MD file
> > >>> >
> > >>> > That said, I'm only in favour of it if we're fastidious about
> > >>> > requiring changelog updates on every single PR. A PR should either
> > >>> > provide a reasonable changelog entry, or, in the body of the PR,
> > >>> > justify it's absence. A simple "This bugfix does not require a
> > >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
> > >>> > for a reviewer to quickly either agree or decide to request (or
> > >>> > provide) an entry.
> > >>> >
> > >>> > If we add the changelog file, we need to update the contributing
> file
> > >>> > to include the new guidelines.
> > >>> >
> > >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
> > mitchell852@gmail.com>
> > >>> wrote:
> > >>> >> Yes, I was about to mention milestones. Why not leverage Github
> > >>> milestones
> > >>> >> on issues/PRs? We talked about using milestones at the last TC
> > summit to
> > >>> >> determine the scope of a release. Now is our chance to do that.
> > >>> >>
> > >>> >> Milestones can be applied to issues or PRs. I tend to create
> issues
> > for
> > >>> >> everything I do, so I would put the milestone on the issue but
> > others
> > >>> can
> > >>> >> simply put a milestone on their PR (if there is no related issue).
> > >>> Either
> > >>> >> way, it tags the items we want included in the changelog. And then
> > the
> > >>> RM
> > >>> >> can build the changelog from the milestones. Easy peasy.
> > >>> >>
> > >>> >> Jeremy
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >>
> > >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
> > wrote:
> > >>> >>
> > >>> >>>
> > >>> >>>
> > >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
> > wrote:
> > >>> >>> >
> > >>> >>> > Looks like this thread died over the holidays.  Let me try to
> > bring
> > >>> it
> > >>> >>> back
> > >>> >>> > up before we cut a 2.2 branch.
> > >>> >>> > Can you please respond with *just* the following:
> > >>> >>> >
> > >>> >>> > [X] +1 to adding a changelog.MD file
> > >>> >>> > [] -1 to adding a changelog.MD file
> > >>> >>> >
> > >>> >>> > [] +1 to adding a changelog label in github
> > >>> >>> > [X] -1 to adding a changelog label in github
> > >>> >>> >
> > >>> >>>
> > >>> >>>
> > >>> >>> To add to the previous thread / thoughts. I feel reasonably
> > strongly
> > >>> that
> > >>> >>> having a changelog label in Github is not useful. In the ATS
> > >>> community, we
> > >>> >>> can *barely* get people to set the Milestone properly, and I feel
> > that
> > >>> the
> > >>> >>> Milestone is a much more important thing to keep accurate than
> > anything
> > >>> >>> else. And, to be normalized, you don’t want to duplicate this
> info
> > :-).
> > >>> >>>
> > >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
> > and
> > >>> then
> > >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
> > >>> Milestones
> > >>> >>> on all PRs closed.
> > >>> >>>
> > >>> >>> Cheers,
> > >>> >>>
> > >>> >>> — leif
> > >>> >>>
> > >>> >>> > Thanks,
> > >>> >>> > Dave
> > >>> >>> >
> > >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> > >>> dewrich@gmail.com>
> > >>> >>> > wrote:
> > >>> >>> >
> > >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the
> changelog
> > >>> label
> > >>> >>> >> because it helps streamline it's creation.  I also think the
> > labels
> > >>> are
> > >>> >>> >> valuable because they help summarize the parts of the repo
> that
> > >>> changed
> > >>> >>> and
> > >>> >>> >> keeps the concept closer to the repository (where the real
> > change
> > >>> is).
> > >>> >>> >>
> > >>> >>> >> -Dew
> > >>> >>> >>
> > >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> > >>> robert.o.butts@gmail.com
> > >>> >>> >
> > >>> >>> >> 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 <
> > neuman@apache.org>
> > >>> >>> 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 <
> > >>> >>> >> mitchell852@gmail.com>
> > >>> >>> >>>> 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 <
> > >>> >>> >> dewrich@gmail.com
> > >>> >>> >>>>
> > >>> >>> >>>>> 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_Gelinas@comcast.com>
> > >>> >>> >>>>>> wrote:
> > >>> >>> >>>>>>
> > >>> >>> >>>>>>> I'm +1 for the label as well.
> > >>> >>> >>>>>>>
> > >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> > >>> >>> >>>> robert.o.butts@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 <
> > >>> >>> >>>>>> dewrich@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 <
> > >>> >>> >>>>>>> mitchell852@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 <
> > >>> >>> >>> neuman@apache.org
> > >>> >>> >>>>>
> > >>> >>> >>>>>>> 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 <
> > >>> >>> >>>>>>>>> mitchell852@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 <
> > >>> >>> >>>> neuman@apache.org>
> > >>> >>> >>>>>>>>>> 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 <
> > >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
> > >>> >>> >>>>>>>>>>>>> wrote:
> > >>> >>> >>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
> > determine
> > >>> >>> >> the
> > >>> >>> >>>>> scope
> > >>> >>> >>>>>>>>> of
> > >>> >>> >>>>>>>>>>>> each
> > >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > >>> >>> >> incubator-trafficcontrol/blob/
> > >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> > >>> >>> >>>>>>>>>>>>>> :
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
> > fixes)
> > >>> for
> > >>> >>> >>>>> Traffic
> > >>> >>> >>>>>>>>>>>>> Control,
> > >>> >>> >>>>>>>>>>>>>> start by creating an issue
> > >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> > incubator-trafficcontrol/
> > >>> >>> >> issues
> > >>> >>> >>>>>> ..."
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> 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.
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
> > >>> >>> >>>>> neuman@apache.org>
> > >>> >>> >>>>>>>>>>>> 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
> <
> > >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>> 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
> > >>> >>> >>>>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>>
> > >>> >>> >>>>>>>>>>>
> > >>> >>> >>>>>>>>>>
> > >>> >>> >>>>>>>>>
> > >>> >>> >>>>>>>
> > >>> >>> >>>>>>
> > >>> >>> >>>>>
> > >>> >>> >>>>
> > >>> >>> >>>
> > >>> >>> >>
> > >>> >>>
> > >>> >>>
> > >>>
> >
>

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

[Jeremy Mitchell <mi...@gmail.com>]

I like that format. Bullets seems nice and simple with external links where
more info is required.

I would be in favor of a PR to add these sections so it's easy for the next
person to add a bullet to the relevant section.

On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
wrote:

> Hey folks,
>
> So I used the influxdb changelog as an example format, but @dew has
> shown me this popular project for changelog convention:
> http://keepachangelog.com/en/1.0.0/. For example see the project
> changelog: https://github.com/olivierlacan/keep-a-changelog/
> blob/master/CHANGELOG.md.
>
> Since we now have a changelog, it would be best to have a standard,
> agreed-upon format for it so that we can keep it consistent for every
> release.
>
> Basically it means every release has its own section (with an
> "unreleased" section at the top), and everything will be
> bullet-pointed underneath one of these sections for every release:
> - "Added" for new features.
> - "Changed" for changes in existing functionality.
> - "Deprecated" for soon-to-be removed features.
> - "Removed" for now removed features.
> - "Fixed" for any bug fixes.
> - "Security" in case of vulnerabilities.
>
> For example with my per-DS routing name upgrade notes currently in the
> changelog, I would add that to the "Added" section and link to the
> upgrade notes in our docs.
>
>  What do you all think? All in favor of accepting this keepachangelog
> format?
>
> - Rawlin
>
>
>
> On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
> > I went ahead and created one:
> > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> > review and merge if you are okay with the current format. I'm not sure
> > if we want to go back and add a list of all the new features in 2.2 or
> > not, but please add to the CHANGELOG.md file if you have any pending
> > release notes like 2.2 upgrade gotchas you'd like to get in.
> >
> > Thanks,
> > Rawlin
> >
> > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
> >> Hey Rawlin,
> >> I think Steve was starting to work on one, so we will see what he says.
> >> If he doesn't have one started, I think you can go ahead and create one.
> >>
> >> Thanks,
> >> Dave
> >>
> >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <ra...@gmail.com>
> >> wrote:
> >>
> >>> Hey all,
> >>>
> >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
> >>> without having a changelog label in GitHub. Is anyone currently
> >>> working on one?
> >>>
> >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
> >>> some upgrade release notes about Per-Delivery-Service Routing Names.
> >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> >>> start one and add those release notes in there (using
> >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
> >>> example template).
> >>>
> >>> -Rawlin
> >>>
> >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
> >>> wrote:
> >>> > [X] +1 to adding a changelog.MD file
> >>> > [] -1 to adding a changelog.MD file
> >>> >
> >>> > That said, I'm only in favour of it if we're fastidious about
> >>> > requiring changelog updates on every single PR. A PR should either
> >>> > provide a reasonable changelog entry, or, in the body of the PR,
> >>> > justify it's absence. A simple "This bugfix does not require a
> >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
> >>> > for a reviewer to quickly either agree or decide to request (or
> >>> > provide) an entry.
> >>> >
> >>> > If we add the changelog file, we need to update the contributing file
> >>> > to include the new guidelines.
> >>> >
> >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
> mitchell852@gmail.com>
> >>> wrote:
> >>> >> Yes, I was about to mention milestones. Why not leverage Github
> >>> milestones
> >>> >> on issues/PRs? We talked about using milestones at the last TC
> summit to
> >>> >> determine the scope of a release. Now is our chance to do that.
> >>> >>
> >>> >> Milestones can be applied to issues or PRs. I tend to create issues
> for
> >>> >> everything I do, so I would put the milestone on the issue but
> others
> >>> can
> >>> >> simply put a milestone on their PR (if there is no related issue).
> >>> Either
> >>> >> way, it tags the items we want included in the changelog. And then
> the
> >>> RM
> >>> >> can build the changelog from the milestones. Easy peasy.
> >>> >>
> >>> >> Jeremy
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
> wrote:
> >>> >>
> >>> >>>
> >>> >>>
> >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
> wrote:
> >>> >>> >
> >>> >>> > Looks like this thread died over the holidays.  Let me try to
> bring
> >>> it
> >>> >>> back
> >>> >>> > up before we cut a 2.2 branch.
> >>> >>> > Can you please respond with *just* the following:
> >>> >>> >
> >>> >>> > [X] +1 to adding a changelog.MD file
> >>> >>> > [] -1 to adding a changelog.MD file
> >>> >>> >
> >>> >>> > [] +1 to adding a changelog label in github
> >>> >>> > [X] -1 to adding a changelog label in github
> >>> >>> >
> >>> >>>
> >>> >>>
> >>> >>> To add to the previous thread / thoughts. I feel reasonably
> strongly
> >>> that
> >>> >>> having a changelog label in Github is not useful. In the ATS
> >>> community, we
> >>> >>> can *barely* get people to set the Milestone properly, and I feel
> that
> >>> the
> >>> >>> Milestone is a much more important thing to keep accurate than
> anything
> >>> >>> else. And, to be normalized, you don’t want to duplicate this info
> :-).
> >>> >>>
> >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
> and
> >>> then
> >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
> >>> Milestones
> >>> >>> on all PRs closed.
> >>> >>>
> >>> >>> Cheers,
> >>> >>>
> >>> >>> — leif
> >>> >>>
> >>> >>> > Thanks,
> >>> >>> > Dave
> >>> >>> >
> >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> >>> dewrich@gmail.com>
> >>> >>> > wrote:
> >>> >>> >
> >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
> >>> label
> >>> >>> >> because it helps streamline it's creation.  I also think the
> labels
> >>> are
> >>> >>> >> valuable because they help summarize the parts of the repo that
> >>> changed
> >>> >>> and
> >>> >>> >> keeps the concept closer to the repository (where the real
> change
> >>> is).
> >>> >>> >>
> >>> >>> >> -Dew
> >>> >>> >>
> >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> >>> robert.o.butts@gmail.com
> >>> >>> >
> >>> >>> >> 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 <
> neuman@apache.org>
> >>> >>> 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 <
> >>> >>> >> mitchell852@gmail.com>
> >>> >>> >>>> 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 <
> >>> >>> >> dewrich@gmail.com
> >>> >>> >>>>
> >>> >>> >>>>> 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_Gelinas@comcast.com>
> >>> >>> >>>>>> wrote:
> >>> >>> >>>>>>
> >>> >>> >>>>>>> I'm +1 for the label as well.
> >>> >>> >>>>>>>
> >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> >>> >>> >>>> robert.o.butts@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 <
> >>> >>> >>>>>> dewrich@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 <
> >>> >>> >>>>>>> mitchell852@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 <
> >>> >>> >>> neuman@apache.org
> >>> >>> >>>>>
> >>> >>> >>>>>>> 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 <
> >>> >>> >>>>>>>>> mitchell852@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 <
> >>> >>> >>>> neuman@apache.org>
> >>> >>> >>>>>>>>>> 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 <
> >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
> >>> >>> >>>>>>>>>>>>> wrote:
> >>> >>> >>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
> determine
> >>> >>> >> the
> >>> >>> >>>>> scope
> >>> >>> >>>>>>>>> of
> >>> >>> >>>>>>>>>>>> each
> >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> >>> >>> >> incubator-trafficcontrol/blob/
> >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> >>> >>> >>>>>>>>>>>>>> :
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
> fixes)
> >>> for
> >>> >>> >>>>> Traffic
> >>> >>> >>>>>>>>>>>>> Control,
> >>> >>> >>>>>>>>>>>>>> start by creating an issue
> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> incubator-trafficcontrol/
> >>> >>> >> issues
> >>> >>> >>>>>> ..."
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> 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.
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
> >>> >>> >>>>> neuman@apache.org>
> >>> >>> >>>>>>>>>>>> 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 <
> >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>> 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
> >>> >>> >>>>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>
> >>> >>> >>>>>>>>>>
> >>> >>> >>>>>>>>>
> >>> >>> >>>>>>>
> >>> >>> >>>>>>
> >>> >>> >>>>>
> >>> >>> >>>>
> >>> >>> >>>
> >>> >>> >>
> >>> >>>
> >>> >>>
> >>>
>

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

[Rawlin Peters <ra...@gmail.com>]

Thanks to all who voted, the vote to standardize our changelog with
the keepachangelog format has passed with no -1s, so I will now open a
PR to reformat our existing changelog to the keepachangelog format.

- Rawlin

On Wed, Feb 28, 2018 at 9:04 AM, Dewayne Richardson <de...@apache.org> wrote:
> Sorry about that double vote (email hiccuped), so in that case -1, which
> keeps my +1
>
> On Wed, Feb 28, 2018 at 9:03 AM, Dewayne Richardson <de...@apache.org>
> wrote:
>
>> +1
>>
>> On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
>> wrote:
>>
>>> Hey folks,
>>>
>>> So I used the influxdb changelog as an example format, but @dew has
>>> shown me this popular project for changelog convention:
>>> http://keepachangelog.com/en/1.0.0/. For example see the project
>>> changelog: https://github.com/olivierlacan/keep-a-changelog/blob/
>>> master/CHANGELOG.md.
>>>
>>> Since we now have a changelog, it would be best to have a standard,
>>> agreed-upon format for it so that we can keep it consistent for every
>>> release.
>>>
>>> Basically it means every release has its own section (with an
>>> "unreleased" section at the top), and everything will be
>>> bullet-pointed underneath one of these sections for every release:
>>> - "Added" for new features.
>>> - "Changed" for changes in existing functionality.
>>> - "Deprecated" for soon-to-be removed features.
>>> - "Removed" for now removed features.
>>> - "Fixed" for any bug fixes.
>>> - "Security" in case of vulnerabilities.
>>>
>>> For example with my per-DS routing name upgrade notes currently in the
>>> changelog, I would add that to the "Added" section and link to the
>>> upgrade notes in our docs.
>>>
>>>  What do you all think? All in favor of accepting this keepachangelog
>>> format?
>>>
>>> - Rawlin
>>>
>>>
>>>
>>> On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
>>> wrote:
>>> > I went ahead and created one:
>>> > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
>>> > review and merge if you are okay with the current format. I'm not sure
>>> > if we want to go back and add a list of all the new features in 2.2 or
>>> > not, but please add to the CHANGELOG.md file if you have any pending
>>> > release notes like 2.2 upgrade gotchas you'd like to get in.
>>> >
>>> > Thanks,
>>> > Rawlin
>>> >
>>> > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
>>> >> Hey Rawlin,
>>> >> I think Steve was starting to work on one, so we will see what he says.
>>> >> If he doesn't have one started, I think you can go ahead and create
>>> one.
>>> >>
>>> >> Thanks,
>>> >> Dave
>>> >>
>>> >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <rawlin.peters@gmail.com
>>> >
>>> >> wrote:
>>> >>
>>> >>> Hey all,
>>> >>>
>>> >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
>>> >>> without having a changelog label in GitHub. Is anyone currently
>>> >>> working on one?
>>> >>>
>>> >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
>>> >>> some upgrade release notes about Per-Delivery-Service Routing Names.
>>> >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
>>> >>> start one and add those release notes in there (using
>>> >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
>>> >>> example template).
>>> >>>
>>> >>> -Rawlin
>>> >>>
>>> >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
>>> >>> wrote:
>>> >>> > [X] +1 to adding a changelog.MD file
>>> >>> > [] -1 to adding a changelog.MD file
>>> >>> >
>>> >>> > That said, I'm only in favour of it if we're fastidious about
>>> >>> > requiring changelog updates on every single PR. A PR should either
>>> >>> > provide a reasonable changelog entry, or, in the body of the PR,
>>> >>> > justify it's absence. A simple "This bugfix does not require a
>>> >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
>>> >>> > for a reviewer to quickly either agree or decide to request (or
>>> >>> > provide) an entry.
>>> >>> >
>>> >>> > If we add the changelog file, we need to update the contributing
>>> file
>>> >>> > to include the new guidelines.
>>> >>> >
>>> >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
>>> mitchell852@gmail.com>
>>> >>> wrote:
>>> >>> >> Yes, I was about to mention milestones. Why not leverage Github
>>> >>> milestones
>>> >>> >> on issues/PRs? We talked about using milestones at the last TC
>>> summit to
>>> >>> >> determine the scope of a release. Now is our chance to do that.
>>> >>> >>
>>> >>> >> Milestones can be applied to issues or PRs. I tend to create
>>> issues for
>>> >>> >> everything I do, so I would put the milestone on the issue but
>>> others
>>> >>> can
>>> >>> >> simply put a milestone on their PR (if there is no related issue).
>>> >>> Either
>>> >>> >> way, it tags the items we want included in the changelog. And then
>>> the
>>> >>> RM
>>> >>> >> can build the changelog from the milestones. Easy peasy.
>>> >>> >>
>>> >>> >> Jeremy
>>> >>> >>
>>> >>> >>
>>> >>> >>
>>> >>> >>
>>> >>> >>
>>> >>> >>
>>> >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
>>> wrote:
>>> >>> >>
>>> >>> >>>
>>> >>> >>>
>>> >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
>>> wrote:
>>> >>> >>> >
>>> >>> >>> > Looks like this thread died over the holidays.  Let me try to
>>> bring
>>> >>> it
>>> >>> >>> back
>>> >>> >>> > up before we cut a 2.2 branch.
>>> >>> >>> > Can you please respond with *just* the following:
>>> >>> >>> >
>>> >>> >>> > [X] +1 to adding a changelog.MD file
>>> >>> >>> > [] -1 to adding a changelog.MD file
>>> >>> >>> >
>>> >>> >>> > [] +1 to adding a changelog label in github
>>> >>> >>> > [X] -1 to adding a changelog label in github
>>> >>> >>> >
>>> >>> >>>
>>> >>> >>>
>>> >>> >>> To add to the previous thread / thoughts. I feel reasonably
>>> strongly
>>> >>> that
>>> >>> >>> having a changelog label in Github is not useful. In the ATS
>>> >>> community, we
>>> >>> >>> can *barely* get people to set the Milestone properly, and I feel
>>> that
>>> >>> the
>>> >>> >>> Milestone is a much more important thing to keep accurate than
>>> anything
>>> >>> >>> else. And, to be normalized, you don’t want to duplicate this
>>> info :-).
>>> >>> >>>
>>> >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
>>> and
>>> >>> then
>>> >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
>>> >>> Milestones
>>> >>> >>> on all PRs closed.
>>> >>> >>>
>>> >>> >>> Cheers,
>>> >>> >>>
>>> >>> >>> — leif
>>> >>> >>>
>>> >>> >>> > Thanks,
>>> >>> >>> > Dave
>>> >>> >>> >
>>> >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
>>> >>> dewrich@gmail.com>
>>> >>> >>> > wrote:
>>> >>> >>> >
>>> >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
>>> >>> label
>>> >>> >>> >> because it helps streamline it's creation.  I also think the
>>> labels
>>> >>> are
>>> >>> >>> >> valuable because they help summarize the parts of the repo that
>>> >>> changed
>>> >>> >>> and
>>> >>> >>> >> keeps the concept closer to the repository (where the real
>>> change
>>> >>> is).
>>> >>> >>> >>
>>> >>> >>> >> -Dew
>>> >>> >>> >>
>>> >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
>>> >>> robert.o.butts@gmail.com
>>> >>> >>> >
>>> >>> >>> >> 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 <
>>> neuman@apache.org>
>>> >>> >>> 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 <
>>> >>> >>> >> mitchell852@gmail.com>
>>> >>> >>> >>>> 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 <
>>> >>> >>> >> dewrich@gmail.com
>>> >>> >>> >>>>
>>> >>> >>> >>>>> 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_Gelinas@comcast.com>
>>> >>> >>> >>>>>> wrote:
>>> >>> >>> >>>>>>
>>> >>> >>> >>>>>>> I'm +1 for the label as well.
>>> >>> >>> >>>>>>>
>>> >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>>> >>> >>> >>>> robert.o.butts@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 <
>>> >>> >>> >>>>>> dewrich@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 <
>>> >>> >>> >>>>>>> mitchell852@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 <
>>> >>> >>> >>> neuman@apache.org
>>> >>> >>> >>>>>
>>> >>> >>> >>>>>>> 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 <
>>> >>> >>> >>>>>>>>> mitchell852@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 <
>>> >>> >>> >>>> neuman@apache.org>
>>> >>> >>> >>>>>>>>>> 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 <
>>> >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
>>> >>> >>> >>>>>>>>>>>>> wrote:
>>> >>> >>> >>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
>>> determine
>>> >>> >>> >> the
>>> >>> >>> >>>>> scope
>>> >>> >>> >>>>>>>>> of
>>> >>> >>> >>>>>>>>>>>> each
>>> >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>>> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>>> >>> >>> >> incubator-trafficcontrol/blob/
>>> >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>>> >>> >>> >>>>>>>>>>>>>> :
>>> >>> >>> >>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
>>> fixes)
>>> >>> for
>>> >>> >>> >>>>> Traffic
>>> >>> >>> >>>>>>>>>>>>> Control,
>>> >>> >>> >>>>>>>>>>>>>> start by creating an issue
>>> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/inc
>>> ubator-trafficcontrol/
>>> >>> >>> >> issues
>>> >>> >>> >>>>>> ..."
>>> >>> >>> >>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>> 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.
>>> >>> >>> >>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
>>> >>> >>> >>>>> neuman@apache.org>
>>> >>> >>> >>>>>>>>>>>> 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 <
>>> >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
>>> >>> >>> >>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>>> 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
>>> >>> >>> >>>>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>>
>>> >>> >>> >>>>>>>>>>
>>> >>> >>> >>>>>>>>>
>>> >>> >>> >>>>>>>
>>> >>> >>> >>>>>>
>>> >>> >>> >>>>>
>>> >>> >>> >>>>
>>> >>> >>> >>>
>>> >>> >>> >>
>>> >>> >>>
>>> >>> >>>
>>> >>>
>>>
>>
>>

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

[Dewayne Richardson <de...@apache.org>]

Sorry about that double vote (email hiccuped), so in that case -1, which
keeps my +1

On Wed, Feb 28, 2018 at 9:03 AM, Dewayne Richardson <de...@apache.org>
wrote:

> +1
>
> On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
>
>> Hey folks,
>>
>> So I used the influxdb changelog as an example format, but @dew has
>> shown me this popular project for changelog convention:
>> http://keepachangelog.com/en/1.0.0/. For example see the project
>> changelog: https://github.com/olivierlacan/keep-a-changelog/blob/
>> master/CHANGELOG.md.
>>
>> Since we now have a changelog, it would be best to have a standard,
>> agreed-upon format for it so that we can keep it consistent for every
>> release.
>>
>> Basically it means every release has its own section (with an
>> "unreleased" section at the top), and everything will be
>> bullet-pointed underneath one of these sections for every release:
>> - "Added" for new features.
>> - "Changed" for changes in existing functionality.
>> - "Deprecated" for soon-to-be removed features.
>> - "Removed" for now removed features.
>> - "Fixed" for any bug fixes.
>> - "Security" in case of vulnerabilities.
>>
>> For example with my per-DS routing name upgrade notes currently in the
>> changelog, I would add that to the "Added" section and link to the
>> upgrade notes in our docs.
>>
>>  What do you all think? All in favor of accepting this keepachangelog
>> format?
>>
>> - Rawlin
>>
>>
>>
>> On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
>> wrote:
>> > I went ahead and created one:
>> > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
>> > review and merge if you are okay with the current format. I'm not sure
>> > if we want to go back and add a list of all the new features in 2.2 or
>> > not, but please add to the CHANGELOG.md file if you have any pending
>> > release notes like 2.2 upgrade gotchas you'd like to get in.
>> >
>> > Thanks,
>> > Rawlin
>> >
>> > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
>> >> Hey Rawlin,
>> >> I think Steve was starting to work on one, so we will see what he says.
>> >> If he doesn't have one started, I think you can go ahead and create
>> one.
>> >>
>> >> Thanks,
>> >> Dave
>> >>
>> >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <rawlin.peters@gmail.com
>> >
>> >> wrote:
>> >>
>> >>> Hey all,
>> >>>
>> >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
>> >>> without having a changelog label in GitHub. Is anyone currently
>> >>> working on one?
>> >>>
>> >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
>> >>> some upgrade release notes about Per-Delivery-Service Routing Names.
>> >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
>> >>> start one and add those release notes in there (using
>> >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
>> >>> example template).
>> >>>
>> >>> -Rawlin
>> >>>
>> >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
>> >>> wrote:
>> >>> > [X] +1 to adding a changelog.MD file
>> >>> > [] -1 to adding a changelog.MD file
>> >>> >
>> >>> > That said, I'm only in favour of it if we're fastidious about
>> >>> > requiring changelog updates on every single PR. A PR should either
>> >>> > provide a reasonable changelog entry, or, in the body of the PR,
>> >>> > justify it's absence. A simple "This bugfix does not require a
>> >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
>> >>> > for a reviewer to quickly either agree or decide to request (or
>> >>> > provide) an entry.
>> >>> >
>> >>> > If we add the changelog file, we need to update the contributing
>> file
>> >>> > to include the new guidelines.
>> >>> >
>> >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
>> mitchell852@gmail.com>
>> >>> wrote:
>> >>> >> Yes, I was about to mention milestones. Why not leverage Github
>> >>> milestones
>> >>> >> on issues/PRs? We talked about using milestones at the last TC
>> summit to
>> >>> >> determine the scope of a release. Now is our chance to do that.
>> >>> >>
>> >>> >> Milestones can be applied to issues or PRs. I tend to create
>> issues for
>> >>> >> everything I do, so I would put the milestone on the issue but
>> others
>> >>> can
>> >>> >> simply put a milestone on their PR (if there is no related issue).
>> >>> Either
>> >>> >> way, it tags the items we want included in the changelog. And then
>> the
>> >>> RM
>> >>> >> can build the changelog from the milestones. Easy peasy.
>> >>> >>
>> >>> >> Jeremy
>> >>> >>
>> >>> >>
>> >>> >>
>> >>> >>
>> >>> >>
>> >>> >>
>> >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
>> wrote:
>> >>> >>
>> >>> >>>
>> >>> >>>
>> >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
>> wrote:
>> >>> >>> >
>> >>> >>> > Looks like this thread died over the holidays.  Let me try to
>> bring
>> >>> it
>> >>> >>> back
>> >>> >>> > up before we cut a 2.2 branch.
>> >>> >>> > Can you please respond with *just* the following:
>> >>> >>> >
>> >>> >>> > [X] +1 to adding a changelog.MD file
>> >>> >>> > [] -1 to adding a changelog.MD file
>> >>> >>> >
>> >>> >>> > [] +1 to adding a changelog label in github
>> >>> >>> > [X] -1 to adding a changelog label in github
>> >>> >>> >
>> >>> >>>
>> >>> >>>
>> >>> >>> To add to the previous thread / thoughts. I feel reasonably
>> strongly
>> >>> that
>> >>> >>> having a changelog label in Github is not useful. In the ATS
>> >>> community, we
>> >>> >>> can *barely* get people to set the Milestone properly, and I feel
>> that
>> >>> the
>> >>> >>> Milestone is a much more important thing to keep accurate than
>> anything
>> >>> >>> else. And, to be normalized, you don’t want to duplicate this
>> info :-).
>> >>> >>>
>> >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
>> and
>> >>> then
>> >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
>> >>> Milestones
>> >>> >>> on all PRs closed.
>> >>> >>>
>> >>> >>> Cheers,
>> >>> >>>
>> >>> >>> — leif
>> >>> >>>
>> >>> >>> > Thanks,
>> >>> >>> > Dave
>> >>> >>> >
>> >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
>> >>> dewrich@gmail.com>
>> >>> >>> > wrote:
>> >>> >>> >
>> >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
>> >>> label
>> >>> >>> >> because it helps streamline it's creation.  I also think the
>> labels
>> >>> are
>> >>> >>> >> valuable because they help summarize the parts of the repo that
>> >>> changed
>> >>> >>> and
>> >>> >>> >> keeps the concept closer to the repository (where the real
>> change
>> >>> is).
>> >>> >>> >>
>> >>> >>> >> -Dew
>> >>> >>> >>
>> >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
>> >>> robert.o.butts@gmail.com
>> >>> >>> >
>> >>> >>> >> 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 <
>> neuman@apache.org>
>> >>> >>> 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 <
>> >>> >>> >> mitchell852@gmail.com>
>> >>> >>> >>>> 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 <
>> >>> >>> >> dewrich@gmail.com
>> >>> >>> >>>>
>> >>> >>> >>>>> 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_Gelinas@comcast.com>
>> >>> >>> >>>>>> wrote:
>> >>> >>> >>>>>>
>> >>> >>> >>>>>>> I'm +1 for the label as well.
>> >>> >>> >>>>>>>
>> >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>> >>> >>> >>>> robert.o.butts@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 <
>> >>> >>> >>>>>> dewrich@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 <
>> >>> >>> >>>>>>> mitchell852@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 <
>> >>> >>> >>> neuman@apache.org
>> >>> >>> >>>>>
>> >>> >>> >>>>>>> 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 <
>> >>> >>> >>>>>>>>> mitchell852@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 <
>> >>> >>> >>>> neuman@apache.org>
>> >>> >>> >>>>>>>>>> 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 <
>> >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
>> >>> >>> >>>>>>>>>>>>> wrote:
>> >>> >>> >>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
>> determine
>> >>> >>> >> the
>> >>> >>> >>>>> scope
>> >>> >>> >>>>>>>>> of
>> >>> >>> >>>>>>>>>>>> each
>> >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>> >>> >>> >> incubator-trafficcontrol/blob/
>> >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>> >>> >>> >>>>>>>>>>>>>> :
>> >>> >>> >>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
>> fixes)
>> >>> for
>> >>> >>> >>>>> Traffic
>> >>> >>> >>>>>>>>>>>>> Control,
>> >>> >>> >>>>>>>>>>>>>> start by creating an issue
>> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/inc
>> ubator-trafficcontrol/
>> >>> >>> >> issues
>> >>> >>> >>>>>> ..."
>> >>> >>> >>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>> 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.
>> >>> >>> >>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
>> >>> >>> >>>>> neuman@apache.org>
>> >>> >>> >>>>>>>>>>>> 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 <
>> >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
>> >>> >>> >>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>>> 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
>> >>> >>> >>>>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>>
>> >>> >>> >>>>>>>>>>>
>> >>> >>> >>>>>>>>>>
>> >>> >>> >>>>>>>>>
>> >>> >>> >>>>>>>
>> >>> >>> >>>>>>
>> >>> >>> >>>>>
>> >>> >>> >>>>
>> >>> >>> >>>
>> >>> >>> >>
>> >>> >>>
>> >>> >>>
>> >>>
>>
>
>

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

[Dewayne Richardson <de...@apache.org>]

+1

On Tue, Feb 27, 2018 at 2:15 PM, Rawlin Peters <ra...@gmail.com>
wrote:

> Hey folks,
>
> So I used the influxdb changelog as an example format, but @dew has
> shown me this popular project for changelog convention:
> http://keepachangelog.com/en/1.0.0/. For example see the project
> changelog: https://github.com/olivierlacan/keep-a-changelog/
> blob/master/CHANGELOG.md.
>
> Since we now have a changelog, it would be best to have a standard,
> agreed-upon format for it so that we can keep it consistent for every
> release.
>
> Basically it means every release has its own section (with an
> "unreleased" section at the top), and everything will be
> bullet-pointed underneath one of these sections for every release:
> - "Added" for new features.
> - "Changed" for changes in existing functionality.
> - "Deprecated" for soon-to-be removed features.
> - "Removed" for now removed features.
> - "Fixed" for any bug fixes.
> - "Security" in case of vulnerabilities.
>
> For example with my per-DS routing name upgrade notes currently in the
> changelog, I would add that to the "Added" section and link to the
> upgrade notes in our docs.
>
>  What do you all think? All in favor of accepting this keepachangelog
> format?
>
> - Rawlin
>
>
>
> On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
> > I went ahead and created one:
> > https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> > review and merge if you are okay with the current format. I'm not sure
> > if we want to go back and add a list of all the new features in 2.2 or
> > not, but please add to the CHANGELOG.md file if you have any pending
> > release notes like 2.2 upgrade gotchas you'd like to get in.
> >
> > Thanks,
> > Rawlin
> >
> > On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
> >> Hey Rawlin,
> >> I think Steve was starting to work on one, so we will see what he says.
> >> If he doesn't have one started, I think you can go ahead and create one.
> >>
> >> Thanks,
> >> Dave
> >>
> >> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <ra...@gmail.com>
> >> wrote:
> >>
> >>> Hey all,
> >>>
> >>> So it appears this vote passed in favor of adding a CHANGELOG.md file
> >>> without having a changelog label in GitHub. Is anyone currently
> >>> working on one?
> >>>
> >>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
> >>> some upgrade release notes about Per-Delivery-Service Routing Names.
> >>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> >>> start one and add those release notes in there (using
> >>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
> >>> example template).
> >>>
> >>> -Rawlin
> >>>
> >>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
> >>> wrote:
> >>> > [X] +1 to adding a changelog.MD file
> >>> > [] -1 to adding a changelog.MD file
> >>> >
> >>> > That said, I'm only in favour of it if we're fastidious about
> >>> > requiring changelog updates on every single PR. A PR should either
> >>> > provide a reasonable changelog entry, or, in the body of the PR,
> >>> > justify it's absence. A simple "This bugfix does not require a
> >>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
> >>> > for a reviewer to quickly either agree or decide to request (or
> >>> > provide) an entry.
> >>> >
> >>> > If we add the changelog file, we need to update the contributing file
> >>> > to include the new guidelines.
> >>> >
> >>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <
> mitchell852@gmail.com>
> >>> wrote:
> >>> >> Yes, I was about to mention milestones. Why not leverage Github
> >>> milestones
> >>> >> on issues/PRs? We talked about using milestones at the last TC
> summit to
> >>> >> determine the scope of a release. Now is our chance to do that.
> >>> >>
> >>> >> Milestones can be applied to issues or PRs. I tend to create issues
> for
> >>> >> everything I do, so I would put the milestone on the issue but
> others
> >>> can
> >>> >> simply put a milestone on their PR (if there is no related issue).
> >>> Either
> >>> >> way, it tags the items we want included in the changelog. And then
> the
> >>> RM
> >>> >> can build the changelog from the milestones. Easy peasy.
> >>> >>
> >>> >> Jeremy
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >>
> >>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org>
> wrote:
> >>> >>
> >>> >>>
> >>> >>>
> >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org>
> wrote:
> >>> >>> >
> >>> >>> > Looks like this thread died over the holidays.  Let me try to
> bring
> >>> it
> >>> >>> back
> >>> >>> > up before we cut a 2.2 branch.
> >>> >>> > Can you please respond with *just* the following:
> >>> >>> >
> >>> >>> > [X] +1 to adding a changelog.MD file
> >>> >>> > [] -1 to adding a changelog.MD file
> >>> >>> >
> >>> >>> > [] +1 to adding a changelog label in github
> >>> >>> > [X] -1 to adding a changelog label in github
> >>> >>> >
> >>> >>>
> >>> >>>
> >>> >>> To add to the previous thread / thoughts. I feel reasonably
> strongly
> >>> that
> >>> >>> having a changelog label in Github is not useful. In the ATS
> >>> community, we
> >>> >>> can *barely* get people to set the Milestone properly, and I feel
> that
> >>> the
> >>> >>> Milestone is a much more important thing to keep accurate than
> anything
> >>> >>> else. And, to be normalized, you don’t want to duplicate this info
> :-).
> >>> >>>
> >>> >>> So, what we do is have the RM be like a hawk over the Milestones,
> and
> >>> then
> >>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
> >>> Milestones
> >>> >>> on all PRs closed.
> >>> >>>
> >>> >>> Cheers,
> >>> >>>
> >>> >>> — leif
> >>> >>>
> >>> >>> > Thanks,
> >>> >>> > Dave
> >>> >>> >
> >>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> >>> dewrich@gmail.com>
> >>> >>> > wrote:
> >>> >>> >
> >>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
> >>> label
> >>> >>> >> because it helps streamline it's creation.  I also think the
> labels
> >>> are
> >>> >>> >> valuable because they help summarize the parts of the repo that
> >>> changed
> >>> >>> and
> >>> >>> >> keeps the concept closer to the repository (where the real
> change
> >>> is).
> >>> >>> >>
> >>> >>> >> -Dew
> >>> >>> >>
> >>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> >>> robert.o.butts@gmail.com
> >>> >>> >
> >>> >>> >> 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 <
> neuman@apache.org>
> >>> >>> 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 <
> >>> >>> >> mitchell852@gmail.com>
> >>> >>> >>>> 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 <
> >>> >>> >> dewrich@gmail.com
> >>> >>> >>>>
> >>> >>> >>>>> 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_Gelinas@comcast.com>
> >>> >>> >>>>>> wrote:
> >>> >>> >>>>>>
> >>> >>> >>>>>>> I'm +1 for the label as well.
> >>> >>> >>>>>>>
> >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> >>> >>> >>>> robert.o.butts@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 <
> >>> >>> >>>>>> dewrich@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 <
> >>> >>> >>>>>>> mitchell852@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 <
> >>> >>> >>> neuman@apache.org
> >>> >>> >>>>>
> >>> >>> >>>>>>> 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 <
> >>> >>> >>>>>>>>> mitchell852@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 <
> >>> >>> >>>> neuman@apache.org>
> >>> >>> >>>>>>>>>> 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 <
> >>> >>> >>>>>>>>>>> mitchell852@gmail.com>
> >>> >>> >>>>>>>>>>>>> wrote:
> >>> >>> >>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to
> determine
> >>> >>> >> the
> >>> >>> >>>>> scope
> >>> >>> >>>>>>>>> of
> >>> >>> >>>>>>>>>>>> each
> >>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> >>> >>> >> incubator-trafficcontrol/blob/
> >>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> >>> >>> >>>>>>>>>>>>>> :
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug
> fixes)
> >>> for
> >>> >>> >>>>> Traffic
> >>> >>> >>>>>>>>>>>>> Control,
> >>> >>> >>>>>>>>>>>>>> start by creating an issue
> >>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> incubator-trafficcontrol/
> >>> >>> >> issues
> >>> >>> >>>>>> ..."
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> 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.
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>> Or....rather 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 <
> >>> >>> >>>>> neuman@apache.org>
> >>> >>> >>>>>>>>>>>> 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 <
> >>> >>> >>>>>>>>>>>> smalenfant@gmail.com
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>> 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
> >>> >>> >>>>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>>
> >>> >>> >>>>>>>>>>>
> >>> >>> >>>>>>>>>>
> >>> >>> >>>>>>>>>
> >>> >>> >>>>>>>
> >>> >>> >>>>>>
> >>> >>> >>>>>
> >>> >>> >>>>
> >>> >>> >>>
> >>> >>> >>
> >>> >>>
> >>> >>>
> >>>
>

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

[Rawlin Peters <ra...@gmail.com>]

Hey folks,

So I used the influxdb changelog as an example format, but @dew has
shown me this popular project for changelog convention:
http://keepachangelog.com/en/1.0.0/. For example see the project
changelog: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md.

Since we now have a changelog, it would be best to have a standard,
agreed-upon format for it so that we can keep it consistent for every
release.

Basically it means every release has its own section (with an
"unreleased" section at the top), and everything will be
bullet-pointed underneath one of these sections for every release:
- "Added" for new features.
- "Changed" for changes in existing functionality.
- "Deprecated" for soon-to-be removed features.
- "Removed" for now removed features.
- "Fixed" for any bug fixes.
- "Security" in case of vulnerabilities.

For example with my per-DS routing name upgrade notes currently in the
changelog, I would add that to the "Added" section and link to the
upgrade notes in our docs.

 What do you all think? All in favor of accepting this keepachangelog format?

- Rawlin



On Thu, Feb 8, 2018 at 2:29 PM, Rawlin Peters <ra...@gmail.com> wrote:
> I went ahead and created one:
> https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
> review and merge if you are okay with the current format. I'm not sure
> if we want to go back and add a list of all the new features in 2.2 or
> not, but please add to the CHANGELOG.md file if you have any pending
> release notes like 2.2 upgrade gotchas you'd like to get in.
>
> Thanks,
> Rawlin
>
> On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
>> Hey Rawlin,
>> I think Steve was starting to work on one, so we will see what he says.
>> If he doesn't have one started, I think you can go ahead and create one.
>>
>> Thanks,
>> Dave
>>
>> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <ra...@gmail.com>
>> wrote:
>>
>>> Hey all,
>>>
>>> So it appears this vote passed in favor of adding a CHANGELOG.md file
>>> without having a changelog label in GitHub. Is anyone currently
>>> working on one?
>>>
>>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
>>> some upgrade release notes about Per-Delivery-Service Routing Names.
>>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
>>> start one and add those release notes in there (using
>>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
>>> example template).
>>>
>>> -Rawlin
>>>
>>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
>>> wrote:
>>> > [X] +1 to adding a changelog.MD file
>>> > [] -1 to adding a changelog.MD file
>>> >
>>> > That said, I'm only in favour of it if we're fastidious about
>>> > requiring changelog updates on every single PR. A PR should either
>>> > provide a reasonable changelog entry, or, in the body of the PR,
>>> > justify it's absence. A simple "This bugfix does not require a
>>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
>>> > for a reviewer to quickly either agree or decide to request (or
>>> > provide) an entry.
>>> >
>>> > If we add the changelog file, we need to update the contributing file
>>> > to include the new guidelines.
>>> >
>>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <mi...@gmail.com>
>>> wrote:
>>> >> Yes, I was about to mention milestones. Why not leverage Github
>>> milestones
>>> >> on issues/PRs? We talked about using milestones at the last TC summit to
>>> >> determine the scope of a release. Now is our chance to do that.
>>> >>
>>> >> Milestones can be applied to issues or PRs. I tend to create issues for
>>> >> everything I do, so I would put the milestone on the issue but others
>>> can
>>> >> simply put a milestone on their PR (if there is no related issue).
>>> Either
>>> >> way, it tags the items we want included in the changelog. And then the
>>> RM
>>> >> can build the changelog from the milestones. Easy peasy.
>>> >>
>>> >> Jeremy
>>> >>
>>> >>
>>> >>
>>> >>
>>> >>
>>> >>
>>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org> wrote:
>>> >>
>>> >>>
>>> >>>
>>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org> wrote:
>>> >>> >
>>> >>> > Looks like this thread died over the holidays.  Let me try to bring
>>> it
>>> >>> back
>>> >>> > up before we cut a 2.2 branch.
>>> >>> > Can you please respond with *just* the following:
>>> >>> >
>>> >>> > [X] +1 to adding a changelog.MD file
>>> >>> > [] -1 to adding a changelog.MD file
>>> >>> >
>>> >>> > [] +1 to adding a changelog label in github
>>> >>> > [X] -1 to adding a changelog label in github
>>> >>> >
>>> >>>
>>> >>>
>>> >>> To add to the previous thread / thoughts. I feel reasonably strongly
>>> that
>>> >>> having a changelog label in Github is not useful. In the ATS
>>> community, we
>>> >>> can *barely* get people to set the Milestone properly, and I feel that
>>> the
>>> >>> Milestone is a much more important thing to keep accurate than anything
>>> >>> else. And, to be normalized, you don’t want to duplicate this info :-).
>>> >>>
>>> >>> So, what we do is have the RM be like a hawk over the Milestones, and
>>> then
>>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
>>> Milestones
>>> >>> on all PRs closed.
>>> >>>
>>> >>> Cheers,
>>> >>>
>>> >>> — leif
>>> >>>
>>> >>> > Thanks,
>>> >>> > Dave
>>> >>> >
>>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
>>> dewrich@gmail.com>
>>> >>> > wrote:
>>> >>> >
>>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
>>> label
>>> >>> >> because it helps streamline it's creation.  I also think the labels
>>> are
>>> >>> >> valuable because they help summarize the parts of the repo that
>>> changed
>>> >>> and
>>> >>> >> keeps the concept closer to the repository (where the real change
>>> is).
>>> >>> >>
>>> >>> >> -Dew
>>> >>> >>
>>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
>>> robert.o.butts@gmail.com
>>> >>> >
>>> >>> >> 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 <ne...@apache.org>
>>> >>> 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 <
>>> >>> >> mitchell852@gmail.com>
>>> >>> >>>> 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 <
>>> >>> >> dewrich@gmail.com
>>> >>> >>>>
>>> >>> >>>>> 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_Gelinas@comcast.com>
>>> >>> >>>>>> wrote:
>>> >>> >>>>>>
>>> >>> >>>>>>> I'm +1 for the label as well.
>>> >>> >>>>>>>
>>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>>> >>> >>>> robert.o.butts@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 <
>>> >>> >>>>>> dewrich@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 <
>>> >>> >>>>>>> mitchell852@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 <
>>> >>> >>> neuman@apache.org
>>> >>> >>>>>
>>> >>> >>>>>>> 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 <
>>> >>> >>>>>>>>> mitchell852@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 <
>>> >>> >>>> neuman@apache.org>
>>> >>> >>>>>>>>>> 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 <
>>> >>> >>>>>>>>>>> mitchell852@gmail.com>
>>> >>> >>>>>>>>>>>>> wrote:
>>> >>> >>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to determine
>>> >>> >> the
>>> >>> >>>>> scope
>>> >>> >>>>>>>>> of
>>> >>> >>>>>>>>>>>> each
>>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>>> >>> >> incubator-trafficcontrol/blob/
>>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>>> >>> >>>>>>>>>>>>>> :
>>> >>> >>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug fixes)
>>> for
>>> >>> >>>>> Traffic
>>> >>> >>>>>>>>>>>>> Control,
>>> >>> >>>>>>>>>>>>>> start by creating an issue
>>> >>> >>>>>>>>>>>>>> <https://github.com/apache/incubator-trafficcontrol/
>>> >>> >> issues
>>> >>> >>>>>> ..."
>>> >>> >>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>> 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.
>>> >>> >>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>> Or....rather 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 <
>>> >>> >>>>> neuman@apache.org>
>>> >>> >>>>>>>>>>>> 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 <
>>> >>> >>>>>>>>>>>> smalenfant@gmail.com
>>> >>> >>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>>> 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
>>> >>> >>>>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>>
>>> >>> >>>>>>>>>>>>
>>> >>> >>>>>>>>>>>
>>> >>> >>>>>>>>>>
>>> >>> >>>>>>>>>
>>> >>> >>>>>>>
>>> >>> >>>>>>
>>> >>> >>>>>
>>> >>> >>>>
>>> >>> >>>
>>> >>> >>
>>> >>>
>>> >>>
>>>

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

[Rawlin Peters <ra...@gmail.com>]

I went ahead and created one:
https://github.com/apache/incubator-trafficcontrol/pull/1865. Please
review and merge if you are okay with the current format. I'm not sure
if we want to go back and add a list of all the new features in 2.2 or
not, but please add to the CHANGELOG.md file if you have any pending
release notes like 2.2 upgrade gotchas you'd like to get in.

Thanks,
Rawlin

On Wed, Feb 7, 2018 at 4:07 PM, Dave Neuman <ne...@apache.org> wrote:
> Hey Rawlin,
> I think Steve was starting to work on one, so we will see what he says.
> If he doesn't have one started, I think you can go ahead and create one.
>
> Thanks,
> Dave
>
> On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <ra...@gmail.com>
> wrote:
>
>> Hey all,
>>
>> So it appears this vote passed in favor of adding a CHANGELOG.md file
>> without having a changelog label in GitHub. Is anyone currently
>> working on one?
>>
>> With the 2.2 release planned for 2/12/18, I'd like to at least put in
>> some upgrade release notes about Per-Delivery-Service Routing Names.
>> If no one has a CHANGELOG.md in progress, I'll take the liberty to
>> start one and add those release notes in there (using
>> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
>> example template).
>>
>> -Rawlin
>>
>> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
>> wrote:
>> > [X] +1 to adding a changelog.MD file
>> > [] -1 to adding a changelog.MD file
>> >
>> > That said, I'm only in favour of it if we're fastidious about
>> > requiring changelog updates on every single PR. A PR should either
>> > provide a reasonable changelog entry, or, in the body of the PR,
>> > justify it's absence. A simple "This bugfix does not require a
>> > changelog entry." is sufficient for trivial bugfixes. That's plenty
>> > for a reviewer to quickly either agree or decide to request (or
>> > provide) an entry.
>> >
>> > If we add the changelog file, we need to update the contributing file
>> > to include the new guidelines.
>> >
>> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <mi...@gmail.com>
>> wrote:
>> >> Yes, I was about to mention milestones. Why not leverage Github
>> milestones
>> >> on issues/PRs? We talked about using milestones at the last TC summit to
>> >> determine the scope of a release. Now is our chance to do that.
>> >>
>> >> Milestones can be applied to issues or PRs. I tend to create issues for
>> >> everything I do, so I would put the milestone on the issue but others
>> can
>> >> simply put a milestone on their PR (if there is no related issue).
>> Either
>> >> way, it tags the items we want included in the changelog. And then the
>> RM
>> >> can build the changelog from the milestones. Easy peasy.
>> >>
>> >> Jeremy
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org> wrote:
>> >>
>> >>>
>> >>>
>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org> wrote:
>> >>> >
>> >>> > Looks like this thread died over the holidays.  Let me try to bring
>> it
>> >>> back
>> >>> > up before we cut a 2.2 branch.
>> >>> > Can you please respond with *just* the following:
>> >>> >
>> >>> > [X] +1 to adding a changelog.MD file
>> >>> > [] -1 to adding a changelog.MD file
>> >>> >
>> >>> > [] +1 to adding a changelog label in github
>> >>> > [X] -1 to adding a changelog label in github
>> >>> >
>> >>>
>> >>>
>> >>> To add to the previous thread / thoughts. I feel reasonably strongly
>> that
>> >>> having a changelog label in Github is not useful. In the ATS
>> community, we
>> >>> can *barely* get people to set the Milestone properly, and I feel that
>> the
>> >>> Milestone is a much more important thing to keep accurate than anything
>> >>> else. And, to be normalized, you don’t want to duplicate this info :-).
>> >>>
>> >>> So, what we do is have the RM be like a hawk over the Milestones, and
>> then
>> >>> run Phil’s fancy pants script to generate the ChangeLog from the
>> Milestones
>> >>> on all PRs closed.
>> >>>
>> >>> Cheers,
>> >>>
>> >>> — leif
>> >>>
>> >>> > Thanks,
>> >>> > Dave
>> >>> >
>> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
>> dewrich@gmail.com>
>> >>> > wrote:
>> >>> >
>> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
>> label
>> >>> >> because it helps streamline it's creation.  I also think the labels
>> are
>> >>> >> valuable because they help summarize the parts of the repo that
>> changed
>> >>> and
>> >>> >> keeps the concept closer to the repository (where the real change
>> is).
>> >>> >>
>> >>> >> -Dew
>> >>> >>
>> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
>> robert.o.butts@gmail.com
>> >>> >
>> >>> >> 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 <ne...@apache.org>
>> >>> 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 <
>> >>> >> mitchell852@gmail.com>
>> >>> >>>> 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 <
>> >>> >> dewrich@gmail.com
>> >>> >>>>
>> >>> >>>>> 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_Gelinas@comcast.com>
>> >>> >>>>>> wrote:
>> >>> >>>>>>
>> >>> >>>>>>> I'm +1 for the label as well.
>> >>> >>>>>>>
>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
>> >>> >>>> robert.o.butts@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 <
>> >>> >>>>>> dewrich@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 <
>> >>> >>>>>>> mitchell852@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 <
>> >>> >>> neuman@apache.org
>> >>> >>>>>
>> >>> >>>>>>> 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 <
>> >>> >>>>>>>>> mitchell852@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 <
>> >>> >>>> neuman@apache.org>
>> >>> >>>>>>>>>> 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 <
>> >>> >>>>>>>>>>> mitchell852@gmail.com>
>> >>> >>>>>>>>>>>>> wrote:
>> >>> >>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to determine
>> >>> >> the
>> >>> >>>>> scope
>> >>> >>>>>>>>> of
>> >>> >>>>>>>>>>>> each
>> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
>> >>> >>>>>>>>>>>>>> <https://github.com/apache/
>> >>> >> incubator-trafficcontrol/blob/
>> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
>> >>> >>>>>>>>>>>>>> :
>> >>> >>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug fixes)
>> for
>> >>> >>>>> Traffic
>> >>> >>>>>>>>>>>>> Control,
>> >>> >>>>>>>>>>>>>> start by creating an issue
>> >>> >>>>>>>>>>>>>> <https://github.com/apache/incubator-trafficcontrol/
>> >>> >> issues
>> >>> >>>>>> ..."
>> >>> >>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>> 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.
>> >>> >>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>> Or....rather 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 <
>> >>> >>>>> neuman@apache.org>
>> >>> >>>>>>>>>>>> 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 <
>> >>> >>>>>>>>>>>> smalenfant@gmail.com
>> >>> >>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>>> 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
>> >>> >>>>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>>
>> >>> >>>>>>>>>>>>
>> >>> >>>>>>>>>>>
>> >>> >>>>>>>>>>
>> >>> >>>>>>>>>
>> >>> >>>>>>>
>> >>> >>>>>>
>> >>> >>>>>
>> >>> >>>>
>> >>> >>>
>> >>> >>
>> >>>
>> >>>
>>

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

[Dave Neuman <ne...@apache.org>]

Hey Rawlin,
I think Steve was starting to work on one, so we will see what he says.
If he doesn't have one started, I think you can go ahead and create one.

Thanks,
Dave

On Wed, Feb 7, 2018 at 4:04 PM, Rawlin Peters <ra...@gmail.com>
wrote:

> Hey all,
>
> So it appears this vote passed in favor of adding a CHANGELOG.md file
> without having a changelog label in GitHub. Is anyone currently
> working on one?
>
> With the 2.2 release planned for 2/12/18, I'd like to at least put in
> some upgrade release notes about Per-Delivery-Service Routing Names.
> If no one has a CHANGELOG.md in progress, I'll take the liberty to
> start one and add those release notes in there (using
> https://github.com/influxdata/influxdb/blob/master/CHANGELOG.md as an
> example template).
>
> -Rawlin
>
> On Wed, Jan 10, 2018 at 10:35 AM, Chris Lemmons <al...@gmail.com>
> wrote:
> > [X] +1 to adding a changelog.MD file
> > [] -1 to adding a changelog.MD file
> >
> > That said, I'm only in favour of it if we're fastidious about
> > requiring changelog updates on every single PR. A PR should either
> > provide a reasonable changelog entry, or, in the body of the PR,
> > justify it's absence. A simple "This bugfix does not require a
> > changelog entry." is sufficient for trivial bugfixes. That's plenty
> > for a reviewer to quickly either agree or decide to request (or
> > provide) an entry.
> >
> > If we add the changelog file, we need to update the contributing file
> > to include the new guidelines.
> >
> > On Wed, Jan 10, 2018 at 9:14 AM, Jeremy Mitchell <mi...@gmail.com>
> wrote:
> >> Yes, I was about to mention milestones. Why not leverage Github
> milestones
> >> on issues/PRs? We talked about using milestones at the last TC summit to
> >> determine the scope of a release. Now is our chance to do that.
> >>
> >> Milestones can be applied to issues or PRs. I tend to create issues for
> >> everything I do, so I would put the milestone on the issue but others
> can
> >> simply put a milestone on their PR (if there is no related issue).
> Either
> >> way, it tags the items we want included in the changelog. And then the
> RM
> >> can build the changelog from the milestones. Easy peasy.
> >>
> >> Jeremy
> >>
> >>
> >>
> >>
> >>
> >>
> >> On Tue, Jan 9, 2018 at 4:56 PM, Leif Hedstrom <zw...@apache.org> wrote:
> >>
> >>>
> >>>
> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <ne...@apache.org> wrote:
> >>> >
> >>> > Looks like this thread died over the holidays.  Let me try to bring
> it
> >>> back
> >>> > up before we cut a 2.2 branch.
> >>> > Can you please respond with *just* the following:
> >>> >
> >>> > [X] +1 to adding a changelog.MD file
> >>> > [] -1 to adding a changelog.MD file
> >>> >
> >>> > [] +1 to adding a changelog label in github
> >>> > [X] -1 to adding a changelog label in github
> >>> >
> >>>
> >>>
> >>> To add to the previous thread / thoughts. I feel reasonably strongly
> that
> >>> having a changelog label in Github is not useful. In the ATS
> community, we
> >>> can *barely* get people to set the Milestone properly, and I feel that
> the
> >>> Milestone is a much more important thing to keep accurate than anything
> >>> else. And, to be normalized, you don’t want to duplicate this info :-).
> >>>
> >>> So, what we do is have the RM be like a hawk over the Milestones, and
> then
> >>> run Phil’s fancy pants script to generate the ChangeLog from the
> Milestones
> >>> on all PRs closed.
> >>>
> >>> Cheers,
> >>>
> >>> — leif
> >>>
> >>> > Thanks,
> >>> > Dave
> >>> >
> >>> > On Fri, Dec 15, 2017 at 9:14 AM, Dewayne Richardson <
> dewrich@gmail.com>
> >>> > wrote:
> >>> >
> >>> >> +1 on the CHANGELOG.md as well, but I like having the changelog
> label
> >>> >> because it helps streamline it's creation.  I also think the labels
> are
> >>> >> valuable because they help summarize the parts of the repo that
> changed
> >>> and
> >>> >> keeps the concept closer to the repository (where the real change
> is).
> >>> >>
> >>> >> -Dew
> >>> >>
> >>> >> On Thu, Dec 14, 2017 at 3:01 PM, Robert Butts <
> robert.o.butts@gmail.com
> >>> >
> >>> >> 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 <ne...@apache.org>
> >>> 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 <
> >>> >> mitchell852@gmail.com>
> >>> >>>> 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 <
> >>> >> dewrich@gmail.com
> >>> >>>>
> >>> >>>>> 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_Gelinas@comcast.com>
> >>> >>>>>> wrote:
> >>> >>>>>>
> >>> >>>>>>> I'm +1 for the label as well.
> >>> >>>>>>>
> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts <
> >>> >>>> robert.o.butts@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 <
> >>> >>>>>> dewrich@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 <
> >>> >>>>>>> mitchell852@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 <
> >>> >>> neuman@apache.org
> >>> >>>>>
> >>> >>>>>>> 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 <
> >>> >>>>>>>>> mitchell852@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 <
> >>> >>>> neuman@apache.org>
> >>> >>>>>>>>>> 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 <
> >>> >>>>>>>>>>> mitchell852@gmail.com>
> >>> >>>>>>>>>>>>> wrote:
> >>> >>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>> Why not leverage Github issues/milestones to determine
> >>> >> the
> >>> >>>>> scope
> >>> >>>>>>>>> of
> >>> >>>>>>>>>>>> each
> >>> >>>>>>>>>>>>>> release? Per our CONTRIBUTING.md
> >>> >>>>>>>>>>>>>> <https://github.com/apache/
> >>> >> incubator-trafficcontrol/blob/
> >>> >>>>>>>>>>>>>> master/CONTRIBUTING.md>
> >>> >>>>>>>>>>>>>> :
> >>> >>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>> "If you have improvements (enhancements or bug fixes)
> for
> >>> >>>>> Traffic
> >>> >>>>>>>>>>>>> Control,
> >>> >>>>>>>>>>>>>> start by creating an issue
> >>> >>>>>>>>>>>>>> <https://github.com/apache/incubator-trafficcontrol/
> >>> >> issues
> >>> >>>>>> ..."
> >>> >>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>> 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.
> >>> >>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>> Or....rather 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 <
> >>> >>>>> neuman@apache.org>
> >>> >>>>>>>>>>>> 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 <
> >>> >>>>>>>>>>>> smalenfant@gmail.com
> >>> >>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>>> 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
> >>> >>>>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>>
> >>> >>>>>>>>>>>>>
> >>> >>>>>>>>>>>>
> >>> >>>>>>>>>>>
> >>> >>>>>>>>>>
> >>> >>>>>>>>>
> >>> >>>>>>>
> >>> >>>>>>
> >>> >>>>>
> >>> >>>>
> >>> >>>
> >>> >>
> >>>
> >>>
>