# 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 records what changed between releases, so a bug which was both

introduced and fixed since the last release needs no entry. trunk is

never released, so fixing a regression which only ever existed on trunk

needs none at all.

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:".

Changes to an MPM are named for the MPM rather than the module which

implements it, e.g. "prefork MPM:" rather than "mpm_prefork:".

The description should be as concise as possible, a maximum of three

lines but ideally one or two; describe the user-visible effect of the

change rather than simply describing how the code was fixed. New

modules or config directives do NOT need to be explained in detail,

that is covered in the documentation.

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.