Closed SergioRAgostinho closed 5 years ago
taketwo
commented
6 years ago Have a look at this project, perhaps it's flexible enough to meet our demands.
Regarding the pitfall, maybe the script can accept start and end commit ids (or timestamps) and create a changelog for everything in between. This will be a bit less automated than specifying a release tag, but way simpler to implement.
SergioRAgostinho
commented
6 years ago Have a look at this project, perhaps it's flexible enough to meet our demands.
It looked like overkill.
Regarding the pitfall, maybe the script can accept start and end commit ids (or timestamps) and create a changelog for everything in between. This will be a bit less automated than specifying a release tag, but way simpler to implement.
I've offloaded this task to git. We can specify just the tag now as originally intended.
I'm halfway through this: I'm now fetching PR info and later building the change log based on it.
SergioRAgostinho
commented
6 years ago It's already generating something like the snippet shown below. I still need to add some authentication because there's a 60 requests per hour limit to access the GitHub API otherwise, plus highlight PRs which broke ABI/API/Behavor.
It's probably important to revisit the uncategorized PRs and label them properly, etc...
libpcl_common:libpcl_cuda:libpcl_features:libpcl_gpu:libpcl_io:libpcl_octree:libpcl_recognition:libpcl_simulation:PCL Apps:PCL Tests:taketwo
commented
6 years ago Oh, looks great! So if I understand correctly, all the PRs in the first section are unlabeled, but as soon as we mark them with some "module" label, they will move to the corresponding section?
Regarding the breaking changes, I think it would be nice to have both a) highlight or icon in the log entries b) separate section in the beginning of the changelog with a summary of breaking changes.
SergioRAgostinho
commented
6 years ago Oh, looks great! So if I understand correctly, all the PRs in the first section are unlabeled, but as soon as we mark them with some "module" label, they will move to the corresponding section?
Yes and they can have more than one module label if needed. A PR which affects multiple modules will appear in each module's section. I will still need to go over the currently available module labels since a bunch of them are still missing.
The general idea is that now, once we merge a PR, we need to ensure that the title is descriptive enough and that the module, changes and platform labels are properly set. A minor maintenance overhead penalty for an improved release experience.
a) highlight or icon in the log entries
Since we have more than one special status: abi change, api change, behavior change and new feature (?); it might be worth to adopt some icons for each.
b) separate section in the beginning of the changelog with a summary of breaking changes.
By summary you mean an actual summary or just an aggregation of all PRs with breaking changes?
SergioRAgostinho
commented
6 years ago Back at this again 👍
taketwo
commented
6 years ago Since we have more than one special status: abi change, api change, behavior change and new feature (?); it might be worth to adopt some icons for each.
On the other hand, easily understandable icons may be hard to find (how do you visualize ABI change?), and also they won't be rendered when viewing changelog not on GitHub. Thus maybe literal tags like [api] or [behavior] are more comprehensible.
By summary you mean an actual summary or just an aggregation of all PRs with breaking changes?
I meant simple aggregation. Then we can manually expand the items with suggestions what to do about these changes, effectively ending up with a rudimentary "migration guide".
SergioRAgostinho
commented
6 years ago The latest flavor. I'm going to open the PR and write some instructions on how use the tool.
New Features:API Changes:ABI Changes:Behavior Changes:Modules:Uncategorized:libpcl_common:libpcl_cuda:libpcl_features:libpcl_gpu:libpcl_io:libpcl_octree:libpcl_recognition:libpcl_simulation:PCL Apps:PCL Tests:
Just opening this to report that I started working on automating the change log generation.
So far the idea is a Python 3 script which queries the GitHub API for all merged PR from a given tag up till now. It looks at the labels from each PR to assign the PR to the appropriate modules and flags the special cases like ABI, API and behaviour changes, as long as the PR is labelled.
Predictable pitfalls from this strategy: we usually branch for each tag release and there are certain PRs which get merged to master but not to the release branch. With the strategy I mentioned those won't be properly parsed. Basically I would need to find the parent commit when the branch occurred.