Difference between revisions of "Commit Guidelines"
From Joomla! Documentation
m (added Category:CMS Maintainers using HotCat) |
m (added Category:Guidelines using HotCat) |
||
| Line 66: | Line 66: | ||
[[Category:CMS Development Reference]] | [[Category:CMS Development Reference]] | ||
[[Category:CMS Maintainers]] | [[Category:CMS Maintainers]] | ||
| + | [[Category:Guidelines]] | ||
Revision as of 09:13, 24 March 2015
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[edit]
Merge-Commit[edit]
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[edit]
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[edit]
When squashing commits, one should follow these naming conventions so the log will become easier to read.
Format[edit]
- <[Prefix]> <Title>. <Issue>
- <Description>
Prefixes[edit]
| Prefix | Meaning |
|---|---|
| sec | Security |
| bug | Bug fix |
| add | Add |
| rem | Remove |
| lng | Language |
| doc | Documentation / Notes |
| imp | Improvement |
A commit may have multiple prefixes. If that’s the case, each goes into its own brackets.
Title[edit]
Use a descriptive title for the commit. Usually the title of the PR will be fine.
Issue[edit]
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[edit]
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[edit]
- [lng] Clarify content smart search plugins. Closes #1833