|
| 1 | +# Changelog Style Guide |
| 2 | + |
| 3 | +## The core rule |
| 4 | + |
| 5 | +**Each bullet describes one user-visible change, written from the user's perspective, in plain language, as a single sentence.** |
| 6 | + |
| 7 | +If you can't explain the change without referencing internal code, components, or refactors, it probably doesn't belong in the changelog. |
| 8 | + |
| 9 | +## Voice and tense |
| 10 | + |
| 11 | +- **Past tense, implied subject.** The section heading (`## Added`, `## Fixed`, `## Changed`) supplies the verb's mood - bullets read as a continuation of it. |
| 12 | + - Good: `Fixed a missing gap between the project filter tabs and the project list.` |
| 13 | + - Good: `Added support for Java 25.` |
| 14 | + - Avoid: `We fixed...`, `This fixes...`, `Fixes...` (present tense), `Will fix...` |
| 15 | +- **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...`). |
| 16 | +- **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. |
| 17 | + |
| 18 | +## Section/verb agreement |
| 19 | + |
| 20 | +The opening verb must match the section it lives under. Don't put "Fixed X" bullets inside `## Added`. |
| 21 | + |
| 22 | +| Section | Typical opening verbs | |
| 23 | +| ------------- | ------------------------------------------------------------------------------- | |
| 24 | +| `## Added` | Added, Introduced, New | |
| 25 | +| `## Changed` | Refreshed, Redesigned, Moved, Renamed, Updated, Consolidated, Improved, Rebuilt | |
| 26 | +| `## Fixed` | Fixed | |
| 27 | +| `## Security` | Fixed (security framing) | |
| 28 | + |
| 29 | +In `## Added`, the leading "Added" is often dropped because it's redundant with the heading: |
| 30 | + |
| 31 | +- `- Server stats inside server settings modal, in info card.` |
| 32 | +- `- Confirmation modal for resubscribing to a server.` |
| 33 | + |
| 34 | +In `## Fixed`, the leading "Fixed" is **kept** in most entries - it reads more clearly. Be consistent within a single entry. |
| 35 | + |
| 36 | +## What to write about |
| 37 | + |
| 38 | +Describe the **observable behavior**, not the implementation. |
| 39 | + |
| 40 | +- Good: `Server CPU and memory graphs no longer freeze on the last value after a hard crash or out-of-memory kill.` |
| 41 | +- Bad: `Refactored the metrics polling hook to clear stale state on socket disconnect.` |
| 42 | + |
| 43 | +- Good: `Historical log files are now fetched in the background when opening the Logs page, so switching between them is instant.` |
| 44 | +- Bad: `Moved log file fetching into a background worker.` |
| 45 | + |
| 46 | +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). |
| 47 | + |
| 48 | +## Specificity |
| 49 | + |
| 50 | +Be specific enough that a user reading the changelog can recognize the thing you're talking about. |
| 51 | + |
| 52 | +- Vague: `Fixed a bug on the project page.` |
| 53 | +- Better: `Fixed project versions table overflowing outside of table. Version tags will now truncate.` |
| 54 | + |
| 55 | +- Vague: `Improved the UI.` |
| 56 | +- Better: `Refreshed the server cards UI for consistency.` |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +## Length |
| 61 | + |
| 62 | +- **One sentence per bullet.** If you need two sentences, you probably have two bullets, or one bullet plus a sub-bullet. |
| 63 | +- Aim for under ~25 words. Long bullets are usually a sign that the change is being over-explained or is actually multiple changes. |
| 64 | +- 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. |
| 65 | + |
| 66 | +## Punctuation |
| 67 | + |
| 68 | +- **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. |
| 69 | +- Use sentence case, not Title Case. |
| 70 | +- Use straight quotes, not curly quotes (`"foo"` not `"foo"`). |
| 71 | +- Use proper code formatting for filenames, flags, and literal strings: `` `.log` ``, `` `Restart` ``. |
| 72 | + |
| 73 | +## Naming things |
| 74 | + |
| 75 | +- Use the public, branded name: **Modrinth App**, **Modrinth Hosting**, **Modrinth** - not "the app", "servers", "Modrinth Servers" (deprecated). Capitalize product names. |
| 76 | +- Refer to UI surfaces by the label the user sees: **Content tab**, **Worlds tab**, **Files tab**, **Logs page**, **server panel**, **project page**, **Discover page**. |
| 77 | +- Capitalize tab and page names when referring to them by name (`the Content tab`), but not when used generically (`browse content`). |
| 78 | + |
| 79 | +## Don't |
| 80 | + |
| 81 | +- **Don't blame.** Avoid "fixed a regression introduced in v0.12.0" - just describe the fix. |
| 82 | +- **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. |
| 83 | +- **Don't reference internal team members or processes.** No "as requested by support", no "per the design review". |
| 84 | +- **Don't apologize or editorialize.** Skip "unfortunately", "finally", "long-awaited", "we know this has been a pain point". State the change. |
| 85 | +- **Don't use vague intensifiers.** "Significantly improved", "much better", "vastly faster" - quantify if you can, otherwise drop the adverb. |
| 86 | +- **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. |
| 87 | +- **Don't use "issue with" / "issue where" as filler.** `Fixed an issue where buttons were misaligned` → `Fixed misaligned buttons.` |
| 88 | + |
| 89 | +## Examples - rewriting weak bullets |
| 90 | + |
| 91 | +| Weak | Better | |
| 92 | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | |
| 93 | +| `Fixed a bug.` | `Fixed project icons becoming extremely bright on hover.` | |
| 94 | +| `Various improvements to the server panel.` | Split into specific bullets, or drop entirely. | |
| 95 | +| `Refactored the logs page to use a new component.` | `Redesigned the Logs page to match the Modrinth Hosting server panel.` | |
| 96 | +| `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.` | |
| 97 | +| `Made some changes to the content tab.` | Either drop, or list each user-visible change as its own bullet. | |
| 98 | +| `Fixed UX issues.` | Name the specific UX issue. | |
| 99 | + |
| 100 | +## Featured release bullets |
| 101 | + |
| 102 | +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. |
| 103 | + |
| 104 | +## Quick checklist before committing a bullet |
| 105 | + |
| 106 | +1. Would a non-developer user understand it? |
| 107 | +2. Does it describe behavior, not implementation? |
| 108 | +3. Is the verb in the right tense for its section? |
| 109 | +4. Does it name the specific surface (tab/page/modal)? |
| 110 | +5. Is it one sentence, ending in a period? |
| 111 | +6. Is there a vague word ("issue", "bug", "various", "some") I can replace with something concrete? |
0 commit comments