Modrinth-plus/standards/maintaining/CHANGELOG.md

Changelog Style Guide

The core rule

Each bullet describes one user-visible change, written from the user's perspective, in plain language, as a single sentence.

If you can't explain the change without referencing internal code, components, or refactors, it probably doesn't belong in the changelog.

Voice and tense

• Past tense, implied subject. The section heading (## Added, ## Fixed, ## Changed) supplies the verb's mood - bullets read as a continuation of it.
  • Good: Fixed a missing gap between the project filter tabs and the project list.
  • Good: Added support for Java 25.
  • Avoid: We fixed..., This fixes..., Fixes... (present tense), Will fix...
• No first person. Don't say "we" or "our" inside a bullet. The exception is featured release callouts that link to a blog post (We've overhauled the Content tab...).
• No second person except for direct user actions. "You" is fine when describing what the user can now do (Joining a server from the app downloads the required content and launches you directly into the server.), but don't address the user gratuitously.

Section/verb agreement

The opening verb must match the section it lives under. Don't put "Fixed X" bullets inside ## Added.

Section	Typical opening verbs
## Added	Added, Introduced, New
## Changed	Refreshed, Redesigned, Moved, Renamed, Updated, Consolidated, Improved, Rebuilt
## Fixed	Fixed
## Security	Fixed (security framing)

In ## Added, the leading "Added" is often dropped because it's redundant with the heading:

• - Server stats inside server settings modal, in info card.
• - Confirmation modal for resubscribing to a server.

In ## Fixed, the leading "Fixed" is kept in most entries - it reads more clearly. Be consistent within a single entry.

What to write about

Describe the observable behavior, not the implementation.

• Good: Server CPU and memory graphs no longer freeze on the last value after a hard crash or out-of-memory kill.

• Bad: Refactored the metrics polling hook to clear stale state on socket disconnect.

• Good: Historical log files are now fetched in the background when opening the Logs page, so switching between them is instant.

• Bad: Moved log file fetching into a background worker.

If a refactor has no user-visible effect, don't list it. Internal cleanup, dependency bumps, and code moves don't belong in the changelog unless they produce a noticeable difference (perf, reliability, consistency).

Specificity

Be specific enough that a user reading the changelog can recognize the thing you're talking about.

• Vague: Fixed a bug on the project page.

• Better: Fixed project versions table overflowing outside of table. Version tags will now truncate.

• Vague: Improved the UI.

• Better: Refreshed the server cards UI for consistency.

Name the page, tab, modal, or feature you're talking about. "The Content tab", "the server panel header", "the Worlds tab", "the project page" - these give the reader a concrete anchor.

Length

• One sentence per bullet. If you need two sentences, you probably have two bullets, or one bullet plus a sub-bullet.
• Aim for under ~25 words. Long bullets are usually a sign that the change is being over-explained or is actually multiple changes.
• Sub-bullets (indented with a tab) are allowed when one change has several facets - see the ## Added section in the v0.12.0 app release for a good example.

Punctuation

• End every bullet with a period. This is inconsistent in the historical file, but periods are the more common pattern and the one to follow going forward.
• Use sentence case, not Title Case.
• Use straight quotes, not curly quotes ("foo" not "foo").
• Use proper code formatting for filenames, flags, and literal strings: `.log`, `Restart`.

Naming things

• Use the public, branded name: Modrinth App, Modrinth Hosting, Modrinth - not "the app", "servers", "Modrinth Servers" (deprecated). Capitalize product names.
• Refer to UI surfaces by the label the user sees: Content tab, Worlds tab, Files tab, Logs page, server panel, project page, Discover page.
• Capitalize tab and page names when referring to them by name (the Content tab), but not when used generically (browse content).

Don't

• Don't blame. Avoid "fixed a regression introduced in v0.12.0" - just describe the fix.
• Don't reference PRs, issues, or commits. The changelog is for users, not contributors - the exception is notable third-party contributions, where you should credit the contributor by linking their GitHub profile (e.g. Added support for Java 25. Thanks to [@username](https://github.com/username)!). Sharing credit for community contributions is encouraged.
• Don't reference internal team members or processes. No "as requested by support", no "per the design review".
• Don't apologize or editorialize. Skip "unfortunately", "finally", "long-awaited", "we know this has been a pain point". State the change.
• Don't use vague intensifiers. "Significantly improved", "much better", "vastly faster" - quantify if you can, otherwise drop the adverb.
• Don't list every sub-fix of a bigger change separately. If you redesigned the server panel header, write one bullet about the redesign rather than six bullets about each moved element.
• Don't use "issue with" / "issue where" as filler. Fixed an issue where buttons were misaligned → Fixed misaligned buttons.

Examples - rewriting weak bullets

Weak	Better
Fixed a bug.	Fixed project icons becoming extremely bright on hover.
Various improvements to the server panel.	Split into specific bullets, or drop entirely.
Refactored the logs page to use a new component.	Redesigned the Logs page to match the Modrinth Hosting server panel.
Fixed an issue where the server address wasn't copyable.	Server address in the panel header can now be clicked to copy it to your clipboard.
Made some changes to the content tab.	Either drop, or list each user-visible change as its own bullet.
Fixed UX issues.	Name the specific UX issue.

Featured release bullets

When an entry has a linked blog post heading (e.g. ## [Introducing Server Projects](/news/article/...)), the bullets underneath summarize the highlights in 1–4 lines, then link out. They don't need to be exhaustive - that's what the blog post is for.

Quick checklist before committing a bullet

1. Would a non-developer user understand it?
2. Does it describe behavior, not implementation?
3. Is the verb in the right tense for its section?
4. Does it name the specific surface (tab/page/modal)?
5. Is it one sentence, ending in a period?
6. Is there a vague word ("issue", "bug", "various", "some") I can replace with something concrete?