styleguide-git-commit-message
styleguide-git-commit-message copied to clipboard
Published
20 hours ago •
slashsbin
slashsbin
/sBin/StyleGuide/Git/CommitMessage
&
Git Commit Message StyleGuide
TOC
- About
- Commit Message Format
- Suggested Emojis
- Tools
- References
- Fun Emoji Usages
- Contributing
- License
About
This is an attempt to standardize the format of commit messages, for the sake of uniformity in git log, best practices for writing commit messages & fun!
Using emojis at the beginning of commit messages, other than being fun, provides a simple way to indicate the intention of that commit, an ease for the eyes when browsing/reviewing git log. It's also a simple measure of the fact that how much that commit is focused on a single purpose, which is a good practice.
If these rules and/or using emojis is an overkill for your productivity or simply losing its purposes, please tailor them to your needs or don't use them.
Summary of the reasons for these conventions:
- Fun!
- Simple navigation through git history (e.g. ignoring style changes).
- Automatic generating of the changelog.
Commit Message Format
<type>(<scope>): <subject>
<body>
<footer>
Message Subject(first line)
- Capitalize the
<subject>. - Do not end the first line with a period.
- Total characters of the first line MUST be Less than or Equal to 50 characters Long.
- Use the present tense ("Add feature" not "Added feature").
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
- Use
<type>to identify what type of changes introduced in this commit; Allowed<type>keywords:- An Emoji(see below for list of Suggested Emojis)
- Or a Text:
- feat: new feature for the user(or :sparkles: emoji)
- fix: bug fix for the user(or :ambulance: emoji)
- docs: changes to the documentation(or :books: emoji)
- style: formatting, missing semi colons, etc; no production code change(or :art: emoji)
- refactor: refactoring production code, eg. renaming a variable(or :tractor: emoji)
- test: adding missing tests, refactoring tests; no production code change(or :microscope: emoji)
- chore: updating grunt tasks etc; no production code change
- If you need more than one keyword or emoji to use, you should probably think twice!. This usally means you need to break this commit into more smaller commits; If thats not the case then separate each emoji with a space.
- Use
<scope>to identify which component this<type>is related to; Example<scope>values:- init
- runner
- watcher
- config
- web-server
- proxy
- etc.
- The
<scope>can also be empty (e.g. if the change is a global or difficult to assign to a single component), in which case the parentheses are omitted.
Message Body
- Includes motivation for the change and contrasts with previous behavior.
- Use the body to explain whats and whys vs. hows.
- Wrap each line of the body at 72 characters.
Message Footer
- Reference issues this commit is related to with the status of that Issue; Ex.
Issue #27,Ref T27orRef T27, T56orFixes T8. - Supported issue tracker status keywords:
- Fixes
- Fixed
- Closes
- Closed
- Resolves
- Resolved
- Ref
- Issue
- Issues
- More info on issue tracker status keywords:
- It's also recommended to use Full URL to the Issues, instead of just issue ID Number; Doing so will ease browsing issues from terminal.
- In the case of multiple issues separate them with commas, Ex.
Closes #27, #56.
Notes
- Use valid MarkDown format in the
<body>. - All WIP(Work In Progress) commits SHOULD have the :construction: Emoji.
- All WIP commits SHOULD be avoided!.
- Referencing Issues by using special keywords like
FixesorResolveswill mark them as closed automatically! For more information about automatic issue closing using ketwords see their documentation(linked above). - There is NO new-line after the
<footer>. - Every emoji text(
:emoji:) is counted as one character!. - See ToDo Grammar StyleGuide for more Information on
@XXXComment Tags.
Suggested Emojis
| Emoji | Raw Emoji Code | Description |
|---|---|---|
| :art: | :art: |
when improving the format/structure of the code |
| :newspaper: | :newspaper: |
when creating a new file |
| :pencil: | :pencil: |
when performing minor changes/fixing the code or language |
| :racehorse: | :racehorse: |
when improving performance |
| :books: | :books: |
when writing docs |
| :bug: | :bug: |
when reporting a bug, with @FIXMEComment Tag |
| :ambulance: | :ambulance: |
when fixing a bug |
| :penguin: | :penguin: |
when fixing something on Linux |
| :apple: | :apple: |
when fixing something on Mac OS |
| :checkered_flag: | :checkered_flag: |
when fixing something on Windows |
| :fire: | :fire: |
when removing code or files, maybe with @CHANGED Comment Tag |
| :tractor: | :tractor: |
when change file structure. Usually together with :art: |
| :hammer: | :hammer: |
when refactoring code |
| :umbrella: | :umbrella: |
when adding tests |
| :microscope: | :microscope: |
when adding code coverage |
| :green_heart: | :green_heart: |
when fixing the CI build |
| :lock: | :lock: |
when dealing with security |
| :arrow_up: | :arrow_up: |
when upgrading dependencies |
| :arrow_down: | :arrow_down: |
when downgrading dependencies |
| :fast_forward: | :fast_forward: |
when forward-porting features from an older version/branch |
| :rewind: | :rewind: |
when backporting features from a newer version/branch |
| :shirt: | :shirt: |
when removing linter/strict/deprecation warnings |
| :lipstick: | :lipstick: |
when improving UI/Cosmetic |
| :wheelchair: | :wheelchair: |
when improving accessibility |
| :globe_with_meridians: | :globe_with_meridians: |
when dealing with globalization/internationalization/i18n/g11n |
| :construction: | :construction: |
WIP(Work In Progress) Commits, maybe with @REVIEW Comment Tag |
| :gem: | :gem: |
New Release |
| :egg: | :egg: |
New Release with Python egg |
| :ferris_wheel: | :ferris_wheel: |
New Release with Python wheel package |
| :bookmark: | :bookmark: |
Version Tags |
| :tada: | :tada: |
Initial Commit |
| :speaker: | :speaker: |
when Adding Logging |
| :mute: | :mute: |
when Reducing Logging |
| :sparkles: | :sparkles: |
when introducing New Features |
| :zap: | :zap: |
when introducing Backward-InCompatible Features, maybe with @CHANGED Comment Tag |
| :bulb: | :bulb: |
New Idea, with @IDEA Comment Tag |
| :snowflake: | :snowflake: |
changing Configuration, Usually together with :penguin: or :ribbon: or :rocket: |
| :ribbon: | :ribbon: |
Customer requested application Customization, with @HACK Comment Tag |
| :rocket: | :rocket: |
Anything related to Deployments/DevOps |
| :elephant: | :elephant: |
PostgreSQL Database specific (Migrations, Scripts, Extensions, ...) |
| :dolphin: | :dolphin: |
MySQL Database specific (Migrations, Scripts, Extensions, ...) |
| :leaves: | :leaves: |
MongoDB Database specific (Migrations, Scripts, Extensions, ...) |
| :bank: | :bank: |
Generic Database specific (Migrations, Scripts, Extensions, ...) |
| :whale: | :whale: |
Docker Configuration |
| :handshake: | :handshake: |
when Merge files |
| :cherries: | :cherries: |
when Commit Arise from one or more Cherry-Pick Commit(s) |
Tools
- Commit(CLI): This is a nifty CLI tool to aid in standardizing commit messages based on this document, thanks to @jakeasmith.
- gitMoji(Firefox & Chrome Extension): Enhance your commits with emojis!, thanks to @louisgrasset.
Fun Emoji Usages
- CodeEmoji: Mozilla’s Codemoji enciphers your messages with emoji for fun and profit
- Emoji Based Diagram: Emoji Based Diagram of Data Bearing Subscription Updates(WebPush VAPID)
Contributing
To add a new Emoji to the list: Create an Issue & Send a PR.
License
The Code is licensed under the MIT License.
slashsbin