diff --git a/README.md b/README.md index d94eea4..9f223eb 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,73 @@ -Commit message format (version 1.7) -=================== +Alternative Commit Message Format (version 0.9) +============================================= -##What is it? -This is a proposal of tags to be used in commit messages. The goal is to identify easily the different types of changes in the project's repo. +## What is it? +This is a proposal of labels to be used in commit messages. The goal is to identify easily the different types of changes in a repo. -##Commit Message rules +## Commit Message rules -####Subject desription (first line) ->1. Prefix the line with an applicable emoji (tag) ->2. Limit the subject line to 50 characters ->3. Separate subject from body with a blank line ->4. Capitalize the subject line ->5. Do not end the subject line with a period ->6. Use the imperative mood in the subject line +Common layout for a commit message (based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)) -####Message body ->7. Wrap the body at 72 characters ->8. Use the body to explain the problems, limitations, and why it is necessary. Then to explain how was addressed the issue and the effects. +``` +[optional scope]: -A complete description, rules and tips can be seen in [1]. +[optional body] - used to explain the what and why of a commit, not the how. Wrap the body at 72 characters in each line. -####Tags and meaning for source code -**NOTE:** The first commit does not have a label, and the message always is "**Initial commit**" as convention. - ->* [api] when functions, methods or classes have been added, modified or removed; method signatures or return types have changed ->* [code] when improving the format/structure of the code, without modifying the previous functionality ->* [main] when dealing with a file that is used as view, notebook or main file ->* [misc] anything not covered by the above categories, e.g. rename or move files, add configuration files, add dataset ->* [new] when adding a new feature (see *Rules* section) ->* [pkg] when libraries, frameworks, packages or modules are added ->* [style] when writing documentation, formatting or comments on code; no code change ->* [test] when adding tests, refactoring tests; no production code change - - - -####Tags and meaning for database +[optional footer(s)] - used to reference issue tracker IDs +``` ->* [ak] alternate key ->* [chk] check restriction ->* [col] column ->* [dt] data type ->* [fk] foreign key ->* [idx] index ->* [mv] materialize view ->* [pk] primary key ->* [seq] sequence ->* [tbl] table ->* [trg] trigger ->* [vw] view +The ***header*** is **mandatory** and the scope of the header is optional. -####Subtags -Those subtags are used in order to provide the action that the commit does ->* *add* when something new has been added ->* *boost* when improving performance ->* *bug* when a bug is found (see *Rules* section) ->* *fix* when fixing a bug (see *Rules* section) ->* *modify* when changes in files have been made ->* *move* when files are moved between directories ->* *remove* when files or directories are deleted ->* *rename* when files or directories are renamed ->* *update* when a package's version is changed, module is added, removed or modified (see *Rules* section) +Any line of the commit message cannot be longer 72 characters! This allows the message to be easier to read on GitHub as well as in various git tools. +The footer should contain a closing reference to an issue if any. -When fixing something on: ->* *and* (*Android*) ->* *ios* ->* *linux* ->* *macos* ->* *win* +A ***scope*** may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays.` +#### Revert -Those subtags must be used just in combination with other tags to specify a particular change related to an O.S. ->Example: -> [api>macos] Subject description - -####Rules -1. The tag [new] is only used when you are doing a merge between a feature-branch and develop. - -2. The tag [update] must be used just when a package is updates ([pkg|update]). - -3. Sometimes when you are doing modifications on your source code, it is likely to find a bug, in this case two actions can occur: - ->+ [api>modify+bug] when the code was modified, a bug was found but NOT fixed ->+ [api>modify+fix] when the code was modified, a bug was found and WAS fixed +If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit ., where the hash is the SHA of the commit being reverted. +#### Subject desription (first line) +1. Prefix the line with an applicable label +2. Limit all the lines (subject included) to 72 characters +3. Use the imperative tone in the subject line +4. Separate subject from body with a blank line +5. Capitalize the subject line +6. Do not end the subject line with a period +#### Main tags and meaning for source code +**NOTE:** The first commit does not have a label, and the message always is "**Initial commit**" as convention. -##REFERENCES +* **core:** The most common day-to-day changes that are created while building a `feature`, that is, methods or classes that have been added (use **Add** in commit message), changed (use **change** in commit message) or removed (use **remove** in commit message), as well as changes to method signatures or to return types. +* **feat:** Changes that introduce new feature to the codebase (this correlates with ***MINOR*** in Semantic Versioning).This is only used when you are doing a merge between a change-branch and source branch. Features may exclusively be targeted for the “master” branch. +* **fix**: A fix commit patches a bug in your codebase (this correlates with ***PATCH*** in Semantic Versioning). +* **pkg:** Used when libraries, frameworks, packages or modules are added. +* **ci:** Changes to the configuration files and scripts. +* **boost**: A code change that improves performance. +* **docs:** Used when writing documentation, formatting comments on code (no code change). +* **test:** Used when adding tests or refactoring tests (no production code change). +* **style:** Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) and do not modify previous funcionality. +* **refactor:** A code change that neither fixes a bug nor adds a feature. +* **task:** Anything not covered by the above categories, e.g. rename or move files, add dataset, etc. +* **BREAKING CHANGE:** A commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking core change (correlating with ***MAJOR*** in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. + +#### Body +Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior. + +#### Footer +The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes. + +Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then the description of the change, justification and migration notes. + +## REFERENCES 1. [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/#why-not-how) Chris Beams 2. [TYPO3 CMS](http://wiki.typo3.org/CommitMessage_Format_(Git)) 3. [Atom](https://atom.io/docs/v0.186.0/contributing) 4. [Karma](http://karma-runner.github.io/0.8/dev/git-commit-msg.html) +5. [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) +6. [Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) ------------- -This document was last modified on : April 6th, 2016. +This document was last modified on : July 9th, 2020.