Documenting Changes

Avid developers often wonder if they are doing the right thing when it comes to the file. If this describes you, fear not. This guide will help you understand this humble file and its use within the Enact framework.


Each Enact library and tool has its own file. This file is located in the corresponding base directory (e.g. the CHANGELOG/ for Moonstone is located in enact/packages/moonstone). The Enact monorepo also has a root-level Developers will primarily concern themselves with the versions located in the libraries and the tools as the root level is only updated before releases.


Developers making API changes, adding or removing components or changing user or developer visible functionality should update the file to call attention to the change. When deciding what to report, err on the side of too much information rather than too little. Some examples may help illustrate this:

Should document

  • Changed the alignment of text within a control
  • Renamed a property
  • Deprecated a component

Probably do not need to document

  • Refactored code
  • Fixed a non-user-visible bug

Comments should be written as markdown and each should begin with a bullet *. Component names should be wrapped in ` and include the library name (`moonstone/Component`, for example).


Each release has its own section within the file. Unreleased changes appear in a section titled unreleased. This section is where developers should insert new entries.

The following sub-sections are available:


This section is used to call attention to new features, properties and components. In this section, it should be assumed that the word ‘Added’ appears before the text. Example:

* `moonstone/NewComponent` Component


This section highlights changes to existing features, properties and components. Example:

* `moonstone/ChangedComponent` to no longer accept the `invalid` property


This section is for highlighting bug fixes that affect developers and end users. If a bug fix actually changes the functionality of a component, it should likely be listed in the Changed section. Example:

* Issue that caused mouse cursor to display upside down