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