> On Jan 9, 2018, at 10:22 AM, Dave Neuman <neu...@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 <dewr...@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.bu...@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 <neu...@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 < >> mitchell...@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 < >> dewr...@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_geli...@comcast.com> >>>>>> wrote: >>>>>> >>>>>>> I'm +1 for the label as well. >>>>>>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts < >>>> robert.o.bu...@gmail.com >>>>>> >>>>>>> wrote: >>>>>>>> >>>>>>>> +1 on a "changelog" label. Seems like that would make it a lot >>>> easier >>>>>> for >>>>>>>> the person writing it up. Easier to skip things like code >>>> maintenance >>>>>>> that >>>>>>>> have no interface effect. >>>>>>>> >>>>>>>> On Thu, Dec 14, 2017 at 10:14 AM, Dewayne Richardson < >>>>>> dewr...@gmail.com> >>>>>>>> wrote: >>>>>>>> >>>>>>>>> Another idea would be to include a new CHANGELOG label that >> you >>>>> could >>>>>>> tack >>>>>>>>> onto specific PR's that you wanted to be included (as well as >>>>> grouped >>>>>>>>> within Milestones) as the high level features that went into >> the >>>>>>> release. >>>>>>>>> As for the gotchas, I think those should be Github issues >>> because >>>> to >>>>>> me >>>>>>>>> those were bugs. >>>>>>>>> >>>>>>>>> -Dew >>>>>>>>> >>>>>>>>> On Thu, Dec 14, 2017 at 10:01 AM, Jeremy Mitchell < >>>>>>> mitchell...@gmail.com> >>>>>>>>> wrote: >>>>>>>>> >>>>>>>>>> I agree. Very 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 < >>> neu...@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 < >>>>>>>>> mitchell...@gmail.com> >>>>>>>>>>> wrote: >>>>>>>>>>> >>>>>>>>>>>> What if CHANGLOG.md includes 2 things: >>>>>>>>>>>> >>>>>>>>>>>> 1. a link to 2.2 issues (i.e. >>>>>>>>>>>> https://github.com/apache/incubator-trafficcontrol/ >>>>>>>>>>>> issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0 >>>>>>>>>>>> 2. a bulleted list of 2.2 gotchas (i.e. Traffic Ops Golang >>>>> doesn't >>>>>>>>>>> connect >>>>>>>>>>>> to a Riak with self-signed certificates; Riak security >> grant >>>>> needs >>>>>>>>>>> updated; >>>>>>>>>>>> upgrade param needed for ds routing names, etc, etc...) >>>>>>>>>>>> >>>>>>>>>>>> But again this requires everyone to create issues (with a >>>>>> milestone) >>>>>>>>> in >>>>>>>>>>>> which one or more PR's can be attached to. >>>>>>>>>>>> >>>>>>>>>>>> Dave, you said "If you are developing a new feature you >> could >>>>>> easily >>>>>>>>>> end >>>>>>>>>>> up >>>>>>>>>>>> with 5 or more PRs" >>>>>>>>>>>> >>>>>>>>>>>> So in this case, I'd expect 1 issue and 5 PR's linked to >>> that 1 >>>>>>>>>> issue... >>>>>>>>>>>> >>>>>>>>>>>> Jeremy >>>>>>>>>>>> >>>>>>>>>>>> On Thu, Dec 14, 2017 at 8:40 AM, Dave Neuman < >>>> neu...@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 < >>>>>>>>>>> mitchell...@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 < >>>>> neu...@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 < >>>>>>>>>>>> smalenf...@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 >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>> >>>>>>>>> >>>>>>> >>>>>> >>>>> >>>> >>> >>
