I had an idea the other day to include a change note directly into each PR.
It shouldn’t be in the branch because that lead to lots of annoying merge conflicts. But writing it in the discussion would do. It could be prefixed by a key word like CHANGENOTE: which makes it easy to extract. These collected notes from each PR/issue in the milestone form a good starting point of the changelog entry for a release.
Whoever merges the PR should make sure there is a change note, but it could also be written by the author or somebody else. This doesn’t need to be strictly enforced, though. It doesn’t matter if it’s missing sometimes. The release notes are manually edited anyway.
The benefit of this approach is that at the time of merging, all relevant information about this change is already aware and it’s less likely to miss details (or even get something wrong) than writing the summary weeks (or months) later.
As an additional effect this makes the description of relevant changes directly visible in the PR. Sometimes PR’s change over time and the original description is not updated. So maybe it would be a good idea to put the CHANGENOTE directly into the original post. This can only be edited by the author or core members, but others can suggest in the comments.
IMHO this should be part of the merge process to ensure proper labels, milestone and presence of an adequate change note. In the best case, a working description of the change is already included in the OP. But I don’t think we need a bot for that.
I wouldn’t want to change the title during the life time of a PR (unless it’s incorrect, obviously), this causes confusion. (I don’t think you suggested that, just wanted to state this in case)
All information we need should be in commit titles and descriptions. This information will be directly in the git repository. We can have it locally, and kept it in case the project moves away from GitHub.
That’s how most CHANGELOG generators do: traverse the git commit log to take the title and description.
A bot could check the commit, if the title and description looks good (Start with a verb, if a description is added if there are lots of changes). A bot isn’t even needed with a git commit pre-hook.
I don’t think every contributor should be required to have the skill/patience to write changelog information in commit history. The PR serves as a discussion and more flexible support.
I see merging and editorial as different things. Also sometimes PR got bundled so the meaning as a whole mutate.
I know it can cause confusion but I am actually in favor of allowing the title to change to reflect that. After the merge IMO, the purpose of the PR is more about browsing and understanding. The activity (and hence, confusion) should be minimum after merge.
@j8r The changelog doesn’t list commits (we have git log for that) but more abstract change sets, which reference the respective PRs of their implementation (which could be multiple; and each PR could add multiple commits). A single commit could also introduce changes that are mentioned in different changelog entries. They are really disparate concepts. Commits represent the internal history of the code, release notes relay the relevant changes to a user.
Agreed. But the merger should a) be aware of the changes and their effects and b) know how a good changelog entry looks like. So it’s good to make sure it’s all right. That doesn’t mean he needs to write this note. Ideally, it’s in the PR from the beginning. But when merging you could check if there is one and whether it accurately reflects the final change set. If not, either write it or leave it to the pre-release editing process.
Changing titles is okay, as long as it helps understanding. Then it doesn’t matter whether the PR is merged or in discussion. But I don’t think we should change titles just to follow some abstract format.
Titles are similar but not identical to change notes. You can’t use markup and links, so it can’t be effectively used for that anyway.