Joomla! Documentation™

Commit Guidelines for the Joomla! CMS.

These guidelines are not meant to be strict rules, but a guide for what we consider best practice.

Merge-Commit vs Squashing

Merge-Commit

When you click the “Merge” button on GitHub, it will create a merge-commit named “Merge pull request #1234 from User/Branch”. This commit will show together with all commits in the PR in the log. Each commit will have the original date when it was created, not when it was actually merged. While this is nice to preserve the actual commit history and is fine with Git Clients which show the branches, it becomes unreadable especially on the GitHub log page.

Squashing

When you squash the commits, you create a single commit consisting of all original commits. This single commit is then pushed to master and can be named in a standardised way.

Recommendation

We recommend to squash the commits in most cases. The “Merge” button in GitHub should only be used for simple PRs with only a few commits and when it’s only a few days old. Most of time, this is the case for simple PRs dealing with codestyle or language strings.

Naming Conventions

When squashing commits, one should follow these naming conventions so the log will become easier to read.

Format

<[Prefix]> <Title>. <Issue>

<Description>

Prefixes

Prefix	Meaning
sec	Security
bug	Bug fix
add	Add
rem	Remove
lang	Language
doc	Documentation / Notes
imp	Improvement
tests	Tests

A commit may have multiple prefixes. If that’s the case, each goes into its own brackets.

Title

Use a descriptive title for the commit. Usually the title of the PR will be fine.

Issue

After the title we add a dot, followed by a text like “Closes #1234”. This will automatically close the PR when the commit is pushed to staging and also provides a link to the PR. See https://help.github.com/articles/closing-issues-via-commit-messages for the available keywords.

Description

The description is optional. It can contain additional information to the commit. Usually that is not needed as the information is available in the linked Pull Request.

Example

[lng] Clarify content smart search plugins. Closes #1833