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