|
| 1 | +--- |
| 2 | +category: framework-contributing |
| 3 | +meta-title: Changelog entries | CKEditor 5 Framework Documentation |
| 4 | +meta-description: Learn how to write structured, user-facing changelog entries for CKEditor 5 using a Markdown-based system designed for clarity, versioning, and long-term maintainability. |
| 5 | +order: 60 |
| 6 | +modified_at: 2025-07-01 |
| 7 | +--- |
| 8 | + |
| 9 | +# Changelog entries |
| 10 | + |
| 11 | +CKEditor 5 uses Markdown file-based changelog system inspired by tools like Changesets. Contributions are noted in a human-readable Markdown files stored in the repository. These files describe the nature of the change (bug fix, feature, breaking change, etc.) and are committed alongside the actual code. These entries will be automatically compiled into the final changelog during the release process. |
| 12 | + |
| 13 | +## How to create a new file |
| 14 | + |
| 15 | +Create a new Markdown file in the `.changelog/` directory to add a changelog entry. Each file **must** describe **one change only**. You can create as many files as you need to explain the changes. |
| 16 | + |
| 17 | +<info-box> |
| 18 | + The easiest and preferred way to create a changelog entry is by running: |
| 19 | + |
| 20 | + ```bash |
| 21 | + yarn run nice |
| 22 | + ``` |
| 23 | + |
| 24 | + `nice` stands for **N**ew **I**ndividual **C**hangelog **E**ntry. |
| 25 | +</info-box> |
| 26 | + |
| 27 | +This command creates a new Markdown file with a file name based on the current date and Git branch name: `YYYYMMDDHHMMSS_{branch-name}.md`. The branch name is automatically slugified (only letters, numbers, `-`, and `_` are allowed). |
| 28 | + |
| 29 | +_Example: `20250617103000_fix-toolbar-alignment.md`_ |
| 30 | + |
| 31 | +The file will include a predefined frontmatter template. **You must manually fill in the details** (like `type`, `scope`, `closes`, and the summary of your change). |
| 32 | + |
| 33 | +## Format of a changelog entry |
| 34 | + |
| 35 | +Each changelog entry is a Markdown file with a frontmatter section followed by a summary and optional context. Here is a breakdown of all available fields: |
| 36 | + |
| 37 | +<table> |
| 38 | + <thead> |
| 39 | + <tr> |
| 40 | + <th style="width: 25%;">Field</th> |
| 41 | + <th style="width: 10%;">Required?</th> |
| 42 | + <th>Description</th> |
| 43 | + </tr> |
| 44 | + </thead> |
| 45 | + <tbody> |
| 46 | + <tr> |
| 47 | + <td><code>type</code></td> |
| 48 | + <td>✅ Yes</td> |
| 49 | + <td> |
| 50 | + Type of the change. See the allowed values and their impact in the table below. |
| 51 | + </td> |
| 52 | + </tr> |
| 53 | + <tr> |
| 54 | + <td><code>scope</code></td> |
| 55 | + <td>❌ No</td> |
| 56 | + <td>Affected package(s), using short names like <code>ckeditor5-core</code>.</td> |
| 57 | + </tr> |
| 58 | + <tr> |
| 59 | + <td><code>closes</code></td> |
| 60 | + <td>❌ No</td> |
| 61 | + <td>List of issues this change resolves. Use numbers (<code>123</code>), full references (<code>ckeditor/ckeditor5#123</code>), or full URLs.</td> |
| 62 | + </tr> |
| 63 | + <tr> |
| 64 | + <td><code>see</code></td> |
| 65 | + <td>❌ No</td> |
| 66 | + <td>Related issues that provide context but are not directly resolved by this change. Same format as <code>closes</code>.</td> |
| 67 | + </tr> |
| 68 | + <tr> |
| 69 | + <td><code>communityCredits</code></td> |
| 70 | + <td>❌ No</td> |
| 71 | + <td>GitHub usernames of external contributors who should be credited for this change.</td> |
| 72 | + </tr> |
| 73 | + <tr> |
| 74 | + <td><em>(body)</em></td> |
| 75 | + <td>✅ Yes</td> |
| 76 | + <td>After the frontmatter, add a short and meaningful summary of the change. Optionally include extended context or rationale.</td> |
| 77 | + </tr> |
| 78 | + </tbody> |
| 79 | +</table> |
| 80 | + |
| 81 | +<info-box> |
| 82 | + **Tip**: Keep the summary clear and user-facing – this is what will appear in the final changelog. |
| 83 | +</info-box> |
| 84 | + |
| 85 | +The changelog entry format is designed to be both human-friendly and machine-readable. It uses a simple frontmatter structure followed by a short description of the change. Each field in the frontmatter serves a specific purpose, from determining the entry's visibility to linking it with related issues or acknowledging community contributions. |
| 86 | + |
| 87 | +Using these fields correctly ensures that the changelog remains accurate, meaningful, and consistent across releases. The sections below explain the available fields in more detail and provide guidance on when and how to use them. |
| 88 | + |
| 89 | +### Allowed values for the `type` field |
| 90 | + |
| 91 | +<table> |
| 92 | + <thead> |
| 93 | + <tr> |
| 94 | + <th style="width: 25%;">Type</th> |
| 95 | + <th style="width: 10%;">Release</th> |
| 96 | + <th>Description</th> |
| 97 | + </tr> |
| 98 | + </thead> |
| 99 | + <tbody> |
| 100 | + <tr> |
| 101 | + <td>Feature</td> |
| 102 | + <td><code>minor</code></td> |
| 103 | + <td>A new feature. Introduces user-facing functionality.</td> |
| 104 | + </tr> |
| 105 | + <tr> |
| 106 | + <td>Fix</td> |
| 107 | + <td><code>patch</code></td> |
| 108 | + <td>A bug fix. Use also for small improvements that do not qualify as new features.</td> |
| 109 | + </tr> |
| 110 | + <tr> |
| 111 | + <td>Other</td> |
| 112 | + <td><code>patch</code></td> |
| 113 | + <td>Enhancement or refactor. It is not a fix or feature. Example: public API cleanup.</td> |
| 114 | + </tr> |
| 115 | + <tr> |
| 116 | + <td>Major breaking change</td> |
| 117 | + <td><code>major</code></td> |
| 118 | + <td>A change in the integration layer or the plugin development API. See {@link updating/versioning-policy versioning policy} for details.</td> |
| 119 | + </tr> |
| 120 | + <tr> |
| 121 | + <td>Minor breaking change</td> |
| 122 | + <td><code>minor</code></td> |
| 123 | + <td>Low-level customizable API layer. See {@link updating/versioning-policy versioning policy} for details.</td> |
| 124 | + </tr> |
| 125 | + </tbody> |
| 126 | +</table> |
| 127 | + |
| 128 | +### Package name (`scope`) |
| 129 | + |
| 130 | +Changes affect one or more packages. List the package that was most impacted by the change first. |
| 131 | + |
| 132 | +However, it is possible to skip this part if many packages are affected. This usually indicates a generic change. In this case, having all the packages listed would reduce the readability of the changelog. |
| 133 | + |
| 134 | +The package name is based on the npm package name, but the `@ckeditor/` prefix is stripped. |
| 135 | + |
| 136 | +If your change is related to the main package, use `ckeditor5` as the package name. |
| 137 | + |
| 138 | +<info-box> |
| 139 | + If the commit introduces a breaking change across the entire project (a generic change), you do not need to specify the package name. |
| 140 | +</info-box> |
| 141 | + |
| 142 | +### Referencing issues |
| 143 | + |
| 144 | +When creating PRs that address specific issues, use the following messages to indicate them. |
| 145 | + |
| 146 | +* `Closes` – When the PR resolves an issue. |
| 147 | +* `See` – When the PR references an issue but has not resolved it yet. |
| 148 | + |
| 149 | +Both fields (`closes` and `see`) can contain multiple references, but they must follow the same format: |
| 150 | + |
| 151 | +* `14724` – A simple issue number. |
| 152 | +* `ckeditor/ckeditor5#14724` – A full reference to an issue in the CKEditor 5 repository. |
| 153 | +* `https://github.com/ckeditor/ckeditor5/issues/14724` – A full URL to an issue in the CKEditor 5 repository. |
| 154 | + |
| 155 | +### Giving credit |
| 156 | + |
| 157 | +When closing a PR submitted by a non-core contributor, add information about the contributor to the changelog entry file using the `communityCredits` field. It should contain a list of GitHub usernames of contributors who should be credited for this change. |
| 158 | + |
| 159 | +### Description |
| 160 | + |
| 161 | +Write a concise and meaningful summary of the change. This main message will appear in the public changelog, so keep it clear, user-facing, and relevant. |
| 162 | + |
| 163 | +Use the `ClassName#methodName()` format when referencing methods. This ensures consistency across all entries. |
| 164 | + |
| 165 | +**Example:** |
| 166 | + |
| 167 | +``` |
| 168 | +MarkerCollection#has() |
| 169 | +``` |
| 170 | + |
| 171 | +You may include multiple sentences if additional context is helpful. |
| 172 | + |
| 173 | +### Examples of correct entry formatting |
| 174 | + |
| 175 | +<info-box> |
| 176 | + Unlike the previous Git-based system, which captured all commit types, including internal changes, the new file-based changelog focuses exclusively on public, user-facing changes, ensuring the final changelog remains clear and relevant to end users. |
| 177 | +</info-box> |
| 178 | + |
| 179 | +A new feature without any breaking changes. |
| 180 | + |
| 181 | +```md |
| 182 | +--- |
| 183 | +type: Feature |
| 184 | +scope: |
| 185 | + - ckeditor5-ui |
| 186 | +closes: |
| 187 | + - 1 |
| 188 | +--- |
| 189 | + |
| 190 | +Added support for RTL languages. |
| 191 | + |
| 192 | +RTL content will now be rendered correctly. |
| 193 | +``` |
| 194 | + |
| 195 | +A generic bug fix for an existing feature that affects many packages (closes two tickets): |
| 196 | + |
| 197 | +```md |
| 198 | +--- |
| 199 | +type: Fix |
| 200 | +closes: |
| 201 | + - 2 |
| 202 | + - 3 |
| 203 | +--- |
| 204 | + |
| 205 | +The editor will be great again. |
| 206 | +``` |
| 207 | + |
| 208 | +An improvement that is not backward compatible and sent by a non-core contributor. Public API was changed: |
| 209 | + |
| 210 | +```md |
| 211 | +--- |
| 212 | +type: Other |
| 213 | +scope: |
| 214 | + - ckeditor5-utils |
| 215 | +closes: |
| 216 | + - 9 |
| 217 | +--- |
| 218 | + |
| 219 | +Extracted the `utils#foo()` to a separate package. |
| 220 | +``` |
| 221 | + |
| 222 | +```md |
| 223 | +--- |
| 224 | +type: Feature |
| 225 | +scope: |
| 226 | + - ckeditor5-engine |
| 227 | +closes: |
| 228 | + - 9 |
| 229 | +--- |
| 230 | + |
| 231 | +Introduced the `engine#foo()` method. |
| 232 | +``` |
| 233 | + |
| 234 | +```md |
| 235 | +--- |
| 236 | +type: Major breaking change |
| 237 | +scope: |
| 238 | + - ckeditor5-utils |
| 239 | +see: |
| 240 | + - 9 |
| 241 | +--- |
| 242 | + |
| 243 | +The `utils#foo()` method was moved to the `engine` package. |
| 244 | +``` |
| 245 | + |
| 246 | +For the entries shown above, the changelog will look like this: |
| 247 | + |
| 248 | +```md |
| 249 | +Changelog |
| 250 | +========= |
| 251 | + |
| 252 | +## [51.0.0](https://github.com/ckeditor/ckeditor5/compare/v50.1.1...v51.0.0) (June 17, 2025) |
| 253 | + |
| 254 | +### MAJOR BREAKING CHANGES [ℹ️](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/versioning-policy.html#major-and-minor-breaking-changes) |
| 255 | + |
| 256 | +* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: The `utils#foo()` method was moved to the `engine` package. See [#9](https://github.com/ckeditor/ckeditor5/issues/9). |
| 257 | + |
| 258 | +### Features |
| 259 | + |
| 260 | +* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Introduced the `engine#foo()` method. Closes [#9](https://github.com/ckeditor/ckeditor5/issues/9). |
| 261 | +* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: Added support for RTL languages. Closes [#1](https://github.com/ckeditor/ckeditor5/issues/1). |
| 262 | + |
| 263 | + RTL content will now be rendered correctly. |
| 264 | + |
| 265 | +### Bug fixes |
| 266 | + |
| 267 | +* The editor will be great again. Closes [#2](https://github.com/ckeditor/ckeditor5/issues/2), [#3](https://github.com/ckeditor/ckeditor5/issues/3). |
| 268 | + |
| 269 | +### Other changes |
| 270 | + |
| 271 | +* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: Extracted the `utils#foo()` to a separate package. Closes [#9](https://github.com/ckeditor/ckeditor5/issues/9). |
| 272 | +``` |
| 273 | + |
| 274 | +### Fixing errors |
| 275 | + |
| 276 | +If the entry message is wrong, you can fix it by editing the Markdown file in the `.changelog/` directory and preparing a new pull request. |
| 277 | + |
| 278 | +## Handling pull requests |
| 279 | + |
| 280 | +When creating a pull request, you may propose a changelog entry (as recommended in the pull request template). |
| 281 | + |
| 282 | +The reviewer must validate the proposed message and apply necessary changes. It can be done using the GitHub interface (as suggestions). |
| 283 | + |
| 284 | +As a reviewer, make sure to check the following aspects of the proposed changelog entry and add or correct them if needed: |
| 285 | + |
| 286 | +* The language and grammar of the message |
| 287 | +* The type of the change |
| 288 | +* Mentioned issue(s) number |
| 289 | +* Breaking changes |
| 290 | +* Any additional relevant information |
| 291 | + |
| 292 | +You must be aware that the message will end up in the changelog and must be understandable in the broad context of the entire editor. It is not for you – it is for other developers. |
| 293 | + |
| 294 | +When closing a PR, you do not have to copy anything. Pick your merge strategy (for example, "Squash and merge"), and GitHub will handle the rest. |
0 commit comments