Skip to content

Commit

Permalink
docs: Update "Writing a good changelog entry" doc (#19347)
Browse files Browse the repository at this point in the history
As of Jetpack 9.7 we're including non-user-facing changes in a section
for that purpose. So update the docs to reflect that.
  • Loading branch information
anomiex authored Mar 30, 2021
1 parent 6583da1 commit 5736961
Showing 1 changed file with 11 additions and 3 deletions.
14 changes: 11 additions & 3 deletions docs/writing-a-good-changelog-entry.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,20 @@ Part of our standard [Pull Request process](./monorepo.md#jetpack-changelogger)

## Do I even need to write a changelog entry?

For Jetpack, our changelog is intended primarily for end users and third-party developers who use our public APIs and packages. Other projects in the Jetpack monorepo also benefit from managing an accurate changelog.
Yes, almost every change to a project should have a changelog entry.

If you've changed something that users will notice, like improving the display of a block or fixing a bug that prevents a feature from working, then by all means submit a suggested changelog entry.
For the Jetpack plugin, our changelog is intended primarily for end users and third-party developers who use our public APIs and packages. As of 9.7, we've added an "Other changes" section for non-user-facing changes.

If you've improved our CI or development environments, or refactored old code without user-visible changes, it's probably not a change that needs a changelog entry intended for end users. However, you would still include a change file with a ["Comment" header](./monorepo.md#using-the-jetpack-changelogger) which would be omitted from the generated changelog, but still serve as documentation to other developers.
Other projects in the Jetpack monorepo also benefit from managing an accurate changelog.

If you've done something really trivial, you would still include a change file with a ["Comment" header](./monorepo.md#using-the-jetpack-changelogger) which would be omitted from the generated changelog, but still serve as documentation to other developers.

If you're ever unsure, feel free to ask for help.

## What should I write?

### In the Jetpack plugin

The actual changelog text typically begins with a relevant component name, feature, tool, or other topic, followed by a colon, such as "Payments Block:" or "Sync:".

The rest of the changelog entry is a sentence fragment (beginning with a bare infinitive verb) describing what the PR does. Remember that this is aimed at end users, so be wary of jargon and details of the code. If it helps, think about filling in the blank "This PR will ______".
Expand All @@ -35,3 +39,7 @@ Some good examples:
* General: update Jetpack's minimum required WordPress version to 5.5, in anticipation of the upcoming WordPress 5.6 release.

You can find more examples by looking at [prior Jetpack releases](https://github.com/Automattic/jetpack-production/releases).

### In other projects

Other projects are generally single components, and so usually do not need a component name prefix. For example, everything in packages/sync would probably be "Sync:". But feel free to use one if it does make sense.

0 comments on commit 5736961

Please sign in to comment.