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