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