# Documenting User-Visible Changes

User-visible changes can be documented in two ways: either by directly
editing the CHANGES file, or by storing each entry for the CHANGES
file correctly formatted in a separate file in the changes-entries
directory.

This covers any developer-visible changes such as a new module API,
but e.g. code cleanups which don't have any externally-visible effect
do not need to be documented in CHANGES.

Changes should be documented by creating a file in changes-entries/
with the .txt suffix, using the following template:

```
  *) mod_foo: Fix bug in blah blah.
     PR <Bugzilla Number>.  [Name of Person <address example.com>,
     Other Person <another example.com>, ...]
```

Changes to server/*.[ch] use a "core:" prefix rather than "mod_foo:".

The description should be as concise as possible, a maximum of three
lines but ideally one or two. The credit for the change goes to the
original patch author(s) and will usually match the "Submitted by: "
tag in the commit message. For current committers, use only the
name and not the e-mail address in the credit. Replace "@" in any
e-mail addresses with a space to prevent address harvesting.

Use a Bugzilla bug number in the PR reference.

# Generating CHANGES from changes-entries/*.txt

The benefit of the single file per change approach is that it eases
backporting the CHANGES entry to a stable branch as it avoids the
frequent merge conflicts as changes are merged in different orders or
not at all in the stable branch.

In order to keep the current CHANGES file for the users as-is, there is a new
make target called 'update-changes'. It merges all change files in the
changes-entries directory to the top of the CHANGES file and removes them
afterwards.

This make target can be seen in a similar way as the scripts to update
the documentation files from the XML sources. It can be executed
immediately after the new file in the changes-entries directory has
been created / merged and committed or it can be executed later. It
should be executed at least before a release gets tagged.