security - the change affects a security issue in any way. Please do not push this commit to any public repo. Instead contact security@elgg.org.

E.g. if your commit refactors to fix a bug, it’s still a “fix”. If that bug is security-related, however, the type
must be “security” and you should email security@elgg.org before proceeding. When in doubt, make your best guess
and a reviewer will provide guidance.

In parenthesis, add the component, a short string which describes the subsystem being changed.

in elgg_foo() you can now pass an array for $bar and the function will... (move detail to description)

removes link color from comments header in river

fixes db so that... (redundant info)

requires non-empty title when saving pages

can save pages with no title (confusingly summarizes old behavior)

(recommended) Skip a line and add a description of the changes. Include the motivation for making them, any info
about back or forward compatibility, and any rationale of why the change had to be done a certain way. Example:

We speed up the Remember Me table migration by using a single INSERT INTO ... SELECT query instead of row-by-row.
This migration takes place during the upgrade to 1.9.

Unless your change is trivial/obvious, a description is required.

If the commit resolves a GitHub issue, skip a line and add Fixes# followed by the issue number. E.g.
Fixes#1234. You can include multiple issues by separating with commas.

GitHub will auto-close the issue when the commit is merged. If you just want to reference an issue, use
Refs# instead.

If your test relies on Elgg’s Service Provider (_elgg_services() returns a Elgg\Di\ServiceProvider), realize that it maintains a singleton instance for most services it hands out, and many services keep their own local references to these services as well.

Due to these local references, replacing services on the SP within a test often will not have the desired effect. Instead, you may need to use functionality baked into the services themselves:

If you are copy-pasting code a significant amount of code, consider whether there’s an opportunity to reduce
duplication by introducing a function, an additional argument, a view, or a new component class.

E.g. If you find views that are identical except for a single value, refactor into a single view
that takes an option.

Note: In a bugfix release, some duplication is preferrable to refactoring. Fix bugs in the simplest
way possible and refactor to reduce duplication in the next minor release branch.

Good comments describe the “why.” Good code describes the “how.” E.g.:

Bad:

// increment $i only when the entity is marked as active.
foreach ($entities as $entity) {
if ($entity->active) {
$i++;
}
}

Good:

// find the next index for inserting a new active entity.
foreach ($entities as $entity) {
if ($entity->active) {
$i++;
}
}

Always include a comment if it’s not obvious that something must be done in a certain way. Other
developers looking at the code should be discouraged from refactoring in a way that would break the code.

Occasionally functions and classes must be deprecated in favor of newer
replacements. Since 3rd party plugin authors rely on a consistent API,
backward compatibility must be maintained, but will not be maintained
indefinitely as plugin authors are expected to properly update their plugins.
In order to maintain backward compatibility, deprecated APIs will follow
these guidelines:

Minor version (1.x) that deprecates an API must include a wrapper
function/class (or otherwise appropriate means) to maintain backward
compatibility, including any bugs in the original function/class.
This compatibility layer uses elgg_deprecated_notice('...','1.11')
to log that the function is deprecated.

The next major revision (2.0) removes the compatibility layer.
Any use of the deprecated API should be corrected before this.