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 <[email protected]> wrote: > +1 > > On Tue, Feb 27, 2018 at 14:50 Jeremy Mitchell <[email protected]> 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 <[email protected]> >> 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 <[email protected]> >> > 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 <[email protected]> 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 < >> [email protected]> >> > >> 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 <[email protected]> >> > >>> 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 < >> > [email protected]> >> > >>> 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 <[email protected]> >> > wrote: >> > >>> >> >> > >>> >>> >> > >>> >>> >> > >>> >>> > On Jan 9, 2018, at 10:22 AM, Dave Neuman <[email protected]> >> > 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 < >> > >>> [email protected]> >> > >>> >>> > 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 < >> > >>> [email protected] >> > >>> >>> > >> > >>> >>> >> 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 < >> > [email protected]> >> > >>> >>> 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 < >> > >>> >>> >> [email protected]> >> > >>> >>> >>>> 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 < >> > >>> >>> >> [email protected] >> > >>> >>> >>>> >> > >>> >>> >>>>> 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 < >> > >>> >>> >>>>>> [email protected]> >> > >>> >>> >>>>>> wrote: >> > >>> >>> >>>>>> >> > >>> >>> >>>>>>> I'm +1 for the label as well. >> > >>> >>> >>>>>>> >> > >>> >>> >>>>>>>> On Dec 14, 2017, at 12:29 PM, Robert Butts < >> > >>> >>> >>>> [email protected] >> > >>> >>> >>>>>> >> > >>> >>> >>>>>>> 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 < >> > >>> >>> >>>>>> [email protected]> >> > >>> >>> >>>>>>>> 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 < >> > >>> >>> >>>>>>> [email protected]> >> > >>> >>> >>>>>>>>> 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 < >> > >>> >>> >>> [email protected] >> > >>> >>> >>>>> >> > >>> >>> >>>>>>> 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 < >> > >>> >>> >>>>>>>>> [email protected]> >> > >>> >>> >>>>>>>>>>> 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 < >> > >>> >>> >>>> [email protected]> >> > >>> >>> >>>>>>>>>> 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 < >> > >>> >>> >>>>>>>>>>> [email protected]> >> > >>> >>> >>>>>>>>>>>>> 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 < >> > >>> >>> >>>>> [email protected]> >> > >>> >>> >>>>>>>>>>>> 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 >> < >> > >>> >>> >>>>>>>>>>>> [email protected] >> > >>> >>> >>>>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>>>>>> 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 >> > >>> >>> >>>>>>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>>> >> > >>> >>> >>>>>>>>>>> >> > >>> >>> >>>>>>>>>> >> > >>> >>> >>>>>>>>> >> > >>> >>> >>>>>>> >> > >>> >>> >>>>>> >> > >>> >>> >>>>> >> > >>> >>> >>>> >> > >>> >>> >>> >> > >>> >>> >> >> > >>> >>> >> > >>> >>> >> > >>> >> > >>
