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