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 <neu...@apache.org> 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 <mitchell...@gmail.com> > 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 <neu...@apache.org> 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 <smalenf...@gmail.com > > > > > 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 > > > > > > > > > >
