Skip to content
This repository has been archived by the owner on Jun 21, 2023. It is now read-only.

Add pr template for drafting changelogs #203

Merged
merged 3 commits into from
Mar 11, 2020

Conversation

chloekraw
Copy link
Contributor

@chloekraw chloekraw commented Mar 10, 2020

This follows the convention set forth by GL JS (example at the bottom of this PR) which makes it compatible with github-release-tools' changelog-draft script if we set it up in the future.

cc/ @mapbox/maps-ios @1ec5

@chloekraw chloekraw changed the title add pr template for drafting changelogs Add pr template for drafting changelogs Mar 10, 2020
@1ec5
Copy link
Contributor

1ec5 commented Mar 10, 2020

Would pull requesters be expected to add these <changelog> tags instead of or in addition to modifying the CHANGELOG.md directly?

Historically, in the gl-native repository, the main downside to maintaining a running changelog document was the high potential for merge conflicts as multiple PRs add blurbs to the same portion of the document. One early mitigation strategy was to split up the release notes by category, since each team member tended to focus on a different portion of the API surface area.

Putting blurbs in the PR description instead of CHANGELOG.md would eliminate the potential for merge conflicts. However, it would also shift the burden of sorting blurbs to the person who prepares the release (if we continue sorting them by importance at all). It would also be more difficult for developers to get a bird’s-eye view of the release currently underway: instead of glancing at CHANGELOG.md’s “master” section, they’d need to browse through all the PRs on the current milestone.

Recently, @nishant-karajgikar called my attention to the union merge strategy. If we expect merge conflicts in CHANGELOG.md to continue to be an issue, perhaps we could enable that merge strategy here. We’d need to be a little more vigilant about bad merges when backporting cherry-picked changes or merging old PRs, lest the blurb wind up in the wrong release’s section.

@chloekraw
Copy link
Contributor Author

chloekraw commented Mar 10, 2020

@1ec5 - thanks for the context. Good to know.

Currently, the proposal is to add the changelog entry in the PR description instead of updating the CHANGELOG.md file. From my perspective, a team can still choose to do both -- adding the entry in the PR description and CHANGELOG.md file.

@chloekraw chloekraw merged commit 33ee616 into master Mar 11, 2020
@chloekraw chloekraw deleted the add-pr-template-changelog-1 branch March 11, 2020 18:22
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants