Skip to content
This repository was archived by the owner on Sep 15, 2025. It is now read-only.

Add changelog entry about changelog itself#546

Merged
mokagio merged 1 commit intotrunkfrom
mokagio/add-changelog-to-changelog
Oct 18, 2022
Merged

Add changelog entry about changelog itself#546
mokagio merged 1 commit intotrunkfrom
mokagio/add-changelog-to-changelog

Conversation

@mokagio
Copy link
Contributor

@mokagio mokagio commented Oct 18, 2022

Description

In #545, @AliSoftware suggested/asked whether to add a template for listing PRs or count on the same pattern from other projects being adopted organically.

I thought about using the addition of the changelog itself as an example to set the standard. By the time I thought of that, though, auto-merge had already kicked in and my push failed. So here we are in a new PR (which will not be listed in the changelog 🙃 )

### Internal Changes

_None._
- Add this changelog file. [#545]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I debated wether to use the full URL, which is more friendly to being used outside of GitHub, where the rendered wouldn't expand #number to a PR URL.

Suggested change
- Add this changelog file. [#545]
- Add this changelog file. [#545](https://github.com/wordpress-mobile/WordPressKit-iOS/pull/545)

I decided against it because:

  • We don't do that in other projects
  • Using the number alone is simpler
  • What are the chances of actually needing these raw changelog notes elsewhere? (If we'll ever need them, it's straightforward to add a parsing step to introduce the full URLs ourselves).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I remember similarly debating about that when I started the CHANGELOG.md in release-toolkit. And sometimes I miss the fact that those are not clickable (while in RELEASE-NOTES.txt file we use in our client app's projects, contributors do add the URL).

But ultimately I agree that it's simpler to just add the PR number alone, reduces the risk of accidental inconsistency (with a bad copy/paste where we'd change the PR number but forgot to update the URL…). And in the seldom cases where we do need to look at the associated PR for a changelog entry, which is not that frequent to be a burden imho, it's not that much effort to enter the URL manually in your browser, so simpler to write wins for that case in my book.

@mokagio mokagio requested a review from a team October 18, 2022 11:30
@mokagio mokagio enabled auto-merge October 18, 2022 11:31
@mokagio mokagio merged commit 43a0103 into trunk Oct 18, 2022
@mokagio mokagio deleted the mokagio/add-changelog-to-changelog branch October 18, 2022 11:47
@mokagio
Copy link
Contributor Author

mokagio commented Oct 18, 2022

And sometimes I miss the fact that those are not clickable

This surprised me, actually, when checking the CHANGELOG.md on trunk. So I'm leaving a note about it here for posterity, as I linked this PR in an internal document about the rationale for the format.

Notice the #545 entry at the end of the changelog doesn't have a link:

image

I guess I got used to the way GitHub handles #number in comments and other text fields, such as those for /release/ notes, that I took it for granted.

Still, all the convenience and downstream tooling considerations highlighted above still apply.

Also worth pointing out that, at this point in time, the process we have in release-toolkit results in linked PR numbers from CHANGELOG.md entries in the GitHub release/ notes. So I'd say we're indeed in a good place.

Raw release notes Rendered release notes
Screen Shot 2022-10-19 at 8 17 23 am image

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants