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 > >>>>>>>>> > >>>>>>>> > >>>>>>> > >>>>>> > >>>>> > >>>> > >>> > >> >
