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:
[] +1 to adding a changelog.MD file [] -1 to adding a changelog.MD file [] +1 to adding a changelog label in github [] -1 to adding a changelog label in github 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 > > > > > > >>>>>>>>> > > > > > > >>>>>>>> > > > > > > >>>>>>> > > > > > > >>>>>> > > > > > > >>>>> > > > > > > >>>> > > > > > > >>> > > > > > > >> > > > > > > > > > > > > > > > > > > > > >
