I think a "changelog" label is alright, but ideally I think individual developers should apply their own discretion and edit the CHANGELOG.md as part of their PR if they feel like it needs an entry. It might be easier to write meaningful entries when it's still fresh in your mind rather than 3-6 months down the road when you've already forgotten what you changed. The label seems like it would allow people to wait those 3-6 months until just before a release to go back through their tagged PRs and add the info all at once.
One thing I'd like to avoid though is merge conflicts on the CHANGELOG.md file from everyone writing to the same spot. For example, OpenStack does something like this for their release notes, so we could try to follow their example [1]. The tl;dr is that each entry gets its own unique file in a releasenotes directory, then the release notes are generated from compiling all the individual files. But, if the rate of editing CHANGELOG.md is low, dealing with the occasional merge conflict might be easier than the tooling. - Rawlin [1] https://docs.openstack.org/reno/latest/user/usage.html 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 >> > > > >>>>>>>>> >> > > > >>>>>>>> >> > > > >>>>>>> >> > > > >>>>>> >> > > > >>>>> >> > > > >>>> >> > > > >>> >> > > > >> >> > > > >> > > >> > >>
