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