The importance of a useful changelog

[Bovelett]

After a ticket was opened in the repo for Plugin Guidelines about Changelog Requirement WordPress/wporg-plugin-guidelines#98 @justintadlock suggested that this could be a good topic for developer education. Which triggered me to research what a useful changelog entails to be able to explain it to all levels. If you are okay with it, I'd love to write that article in collaboration.

Goal of the article

While the official title is TBD, this article aims to provide plugin and theme developers with clear, practical guidance on writing meaningful changelogs for the WordPress.org repository. While changelogs are often overlooked, they are critical for transparency, trust, and long-term project sustainability. It aims to give both new and experienced contributors a reference that not only improves user confidence but also educates how a proper changelog can reduce developer support burden and ensures better project maintainability.

related article proposal

I see that there is an article in progress since January 2024 called "Writing a great plugin readme for WordPress.org" here: #366 and I am not sure if writing a proper and useful changelog is part of that already.

[bph]

Hi there @Bovelett So nice to read from you. Thank you so much for your topic idea!

• Writing a great plugin readme for WordPress.org #366 seems to be abandoned, so if you want to move forward, would you want to combine the two ideas? They are pretty close....

The next editorial meeting will be on Sep. 4, when a group of contributors discusses upcoming topics for approval.

[Bovelett]

Thank you @bph! I put the meeting on my calendar. Let's discuss combining them then. Because I suspect it will take some planning for me to talk to a few people about it. And for that I would love some direction. I already have a rough draft for the changelog article. Is it recommended to share that here already, or should I wait until the meeting?

[justintadlock]

@Bovelett - Yes, you are welcome to share a draft this early.

---

I'd argue against combining the readme and changelog articles. They are very different things (yes, I know DotOrg supports a changelog section in its readme.txt). But there is a widely supported standard for changelog files: https://keepachangelog.com/en/1.1.0/

Of, if you prefer, a stricter subset: https://common-changelog.org/

[bph]

The topic was approved; the conversation continues on this issue.

• The importance of a useful changelog #400