Uncoupling summaries from pull requests?

[lagru]

One critique of the approach taken by changelist, is that the relation between pull requests and a summary (a single bullet point) in the release notes isn't always 1-to-1. E.g.

• 1pr-to-many: A pull requests addresses multiple things which should ideally appear as multiple summaries. Possibly even in separate sections.
• many-to-1sum: A change or update is realized in multiple pull requests. However, thematically the entire change or description should go into one summary.

I've been thinking about how we could address these concerns. For 1pr-to-many, we could allow multiple release-note blocks in a pull request description. The only question would be, how to encode the labels for each of these items. Maybe something like (ignore escaping \)

\```release-note
{{label: Enhancement}} Add new `mask` parameter to `foo` to allow masking of values.
\```

\```release-note
{{label: Bug fix}} Fix endless loop in `foo` if NaN is passed as input. 
\```

This would basically override the pull request title (as it already does) and additionally the labels. Personally I'd like to have this option to address cases where the pull requests scoping is difficult.

Still brainstorming an approach to account for many-to-1sum. Maybe something like

\```release-note
{{link: #2381}}
\```

I am not settled on the syntax or details yet. But I am curious what you think?

[bsipocz]

This is why I really like the towncrier approach to changelog, those files are easily editable and belong to the git history.

[bsipocz]

The multiple section suggestion looks good, though the linking one could be problematic if it links to 1) pr with multiple entries, 2) some rewording of the original would be needed due to the new pr, 3) the original entry changes along the line

[lagru]

Agreed on the approach taken by towncrier, and it's also the one I'd prefer personally for mature projects.

In my mind changelist fills the niche between using heavy artillery like towncrier, and GitHub's generated changelog. So I think this suggestion could help with moving changelist a bit closer to towncrier without having the arguably higher barrier of adding files (which totally has advantages too!). I think we should definitely add a section to the README with alternatives and how changelist defines its scope in regards to those alternatives. That would help me with feature scoping and decision making.

[jarrodmillman]

As long as it is optional, this is fine with me. My interest is in making this as simple and as automated as possible. If this gets to complicated, I would likely just move back to https://github.com/github-changelog-generator/github-changelog-generator.

[lagru]

if it links to 1) pr with multiple entries, 2) some rewording of the original would be needed due to the new pr, 3) the original entry changes along the line

I'd address most of these failure modes with sanity checks in the implementation, which isn't ideal. And yes, most of these cases would require editing already merge previous PR descriptions, which is easy to do.