Skip to content

Commit 55209bf

Browse files
eclipse313eclipse313
committed
docs: created initial version of docs 📚
1 parent c67634b commit 55209bf

File tree

4 files changed

+356
-0
lines changed

4 files changed

+356
-0
lines changed

‎README.md‎

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
# Conventional-Commit Plus ✨
2+
3+
📘 [**Specification**](#specification) - 🤓 [**Cheat-Sheet**](#cheat-sheet) - :octocat: [**Git Hooks**](#automatic-setup-with-git-hooks) - 🚓 [**Commitlint**](#specification)
4+
5+
Conventional-Commit Plus is a round-up of my accumulated knowledge on the subject of commits. The project is on the one hand a cheat sheet with all the information I have gathered on this topic and consider useful. On the other hand this is a package that can be used to configure Commitlint. The structure proposed here is a marriage of [Conventional Commits](https://www.conventionalcommits.org) and [Gitmoji](https://gitmoji.dev/).
6+
7+
The following topics will be covered:
8+
9+
- [General information about Conventional Commits](#about-conventional-commits)
10+
- [What is the benefit of Conventional Commits (Plus)?](#why-use-conventional-commits-in-general)
11+
- [The specifications of Conventional Commits Plus](#specification)
12+
- [Cheat-Sheet: available types for commits](#cheat-sheet) _← Probably you are looking for this_
13+
- [Automatic emojis with Git Hooks](#automatic-setup-with-git-hooks)
14+
- [Automatic linting with commitlint](#linting-with-commitlint)
15+
- [A few words in closing](concluding-remarks)
16+
17+
After following this guide, you may have **beautiful commit messages** in your repository that follow the well machine readable and widely used **Conventional Commits** but are still as **nice to look at** as Gitmoji. By using Git Hooks, you **won't incur any additional work** and commitlinter will ensure **high-quality commits across all contributors** and you can generate automatic changelogs or use semantic versioning:
18+
19+
![Screenshot of GitHub repository](assets/img/github.png)
20+
21+
## About Conventional Commits
22+
23+
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. Check out [the specification](https://www.conventionalcommits.org) for more informations. Conventional commits, for example, make it easy to create automated changelogs.
24+
25+
Besides conventional commits, there are also other approaches and attempts to generalize commit messages and make them easier to understand. Another approach to classify commits is [Gitmoji](https://gitmoji.dev/). Here, instead of defined code words, emojis are used to categorize the commits.
26+
27+
Conventional commits define a certain structure of the commit message. An example of a commit using this structure might look like the following:
28+
29+
```
30+
feat(api): allow provided config object to extend other configs
31+
```
32+
33+
### Personal option and motivation
34+
35+
I believe that it makes sense and is necessary in larger projects to agree on a uniform standard of commits. Conventional commits are widely used and easily readable by machines due to their simple structure. Gitmoji rather follows the approach to design the commits in such a way that they are visually distinguished from each other by the emojis. Here I see the big disadvantage that the emojis look nice, but their meaning is not as clear - especially if you are not familiar with it - as the types of conventional commits.
36+
37+
For this reason, I decided to bring together what I consider the best of both worlds and create this repository.
38+
39+
## Why use Conventional Commits Plus
40+
41+
It is widely agreed that people can absorb information quickly, especially through visual stimuli.[^1] This is my motivation to extend conventional commits with emojis and to transfer this visual component into commits. Furthermore, the claim is not to violate any rules of conventional commits in order to maintain full support and backwards compatibility.
42+
43+
### Why use conventional commits in general?
44+
45+
The [specification](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits) of Conventional Commits summarizes the advantages nicely:
46+
47+
- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
48+
- Automatically generating CHANGELOGs.
49+
- Automatically determining a semantic version bump (based on the types of commits landed).
50+
- Communicating the nature of changes to teammates, the public, and other stakeholders.
51+
- Triggering build and publish processes.
52+
53+
## Specification
54+
55+
Conventional Commit Plus extends the original specification to the following commit message structure:
56+
57+
```
58+
<type>[optional scope]: <description> <emoji>
59+
60+
[optional body]
61+
62+
[optional footer(s)]
63+
```
64+
65+
The [original specifications](https://www.conventionalcommits.org/en/v1.0.0/#specification) are retained and are expanded as follows:
66+
67+
- The `emoji` MUST be present in every commit and MUST match the specified emoji of the type.
68+
69+
### Example
70+
71+
So a complete commit message could now look like this, for example:
72+
73+
```
74+
fix(api): prevent racing of requests 🐛
75+
76+
Introduce a request id and a reference to latest request. Dismiss
77+
incoming responses other than from latest request.
78+
79+
Remove timeouts which were used to mitigate the racing issue but are
80+
obsolete now.
81+
82+
Reviewed-by: eclipse313
83+
Refs: #123
84+
```
85+
86+
Examples of shorter messages might be:
87+
88+
```
89+
docs: correct spelling of CHANGELOG 📚
90+
```
91+
92+
```
93+
feat(lang): add German language ✨
94+
```
95+
96+
## Cheat-Sheet
97+
98+
### <a name="table"></a>Overview of available types
99+
100+
The types are oriented to [Commitlint Config Commitlint Config](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional#type-enum), that in turn is based on the [Angular convention](https://github.com/angular/angular/blob/2.0.x/CONTRIBUTING.md#-commit-message-guidelines).
101+
102+
| Typ | Emoji | Title |
103+
| -------- | ----- | ----------------------------------- |
104+
| build | 🏗️ | [Builds](#build) |
105+
| chore | 🔧 | [Chores](#chore) |
106+
| ci | 👷 | [Continuous Integrations](#ci) |
107+
| docs | 📚 | [Documentation](#docs) |
108+
| feat | ✨ | [Features](#feat) |
109+
| fix | 🐛 | [Bug Fixes](#fix) |
110+
| perf | 🏎 | [Performance Improvements](#perf) |
111+
| refactor | ♻️ | [Code Refactoring](#refactor) |
112+
| revert | ⏪️ | [Reverts](#revert) |
113+
| style | 🎨 | [Styles](#style) |
114+
| test | 🧪 | [Tests](#test) |
115+
| wip | 🚧 | [Uncompleted Changes](#wip) |
116+
117+
### Detailed description of types
118+
119+
#### <a name="build"></a>Builds 🏗️
120+
121+
**Type:** `build`
122+
123+
Changes that related to the **build system** or **external dependencies** (example scopes: gulp, broccoli, npm), such as build scripts, package dependencies, and tools used to build the project. This can include changes to the build process, configuration files, and environment variables.
124+
125+
| ✅ Use for | ❌ Don't use for |
126+
| ---------------------------------------------------- | ---------------------------------------------------------------- |
127+
| Update dependency on package X to version Y | Update README file with instructions on how to build the project |
128+
| Update build script to use newer version of compiler |
129+
| Change configuration in `.prettierc` |
130+
131+
⬆️ [Back to overview](#table)
132+
133+
#### <a name="chore"></a>Chores 🔧
134+
135+
**Type:** `chore`
136+
137+
Changes that are made to the codebase that **don't** modify the source code itself or the test suite.
138+
139+
| ✅ Use for | ❌ Don't use for |
140+
| ---------- | ----------------------------------- |
141+
| | Update the header of the login page |
142+
| | Changed year of copyright |
143+
144+
⬆️ [Back to overview](#table)
145+
146+
#### <a name="ci"></a>Continuous Integrations 👷
147+
148+
**Type:** `ci`
149+
150+
Changes that are made to the **Continuous Integration (CI) system** (example scopes: Travis, Circle, BrowserStack, SauceLabs). This can include updates to the configuration files, scripts, or other tools used to automate testing and deployment.
151+
152+
| ✅ Use for | ❌ Don't use for |
153+
| --------------------------------------------------------- | ------------------------------------------- |
154+
| Update build configuration for new deployment environment | Update dependency on package X to version Y |
155+
| Add new automated tests to the CI pipeline |
156+
| Fix issue with test coverage reporting |
157+
158+
⬆️ [Back to overview](#table)
159+
160+
#### <a name="docs"></a>Documentation 📚
161+
162+
**Type:** `docs`
163+
164+
Changes that are made to the **documentation of the project**. This may include updates to the user guide, API documentation, README files, and other forms of documentation.
165+
166+
| ✅ Use for | ❌ Don't use for |
167+
| ------------------------------------------------------- | ------------------------------------------------------------ |
168+
| Update user guide with new screenshots and instructions | Provided better explanation for password reset on login page |
169+
| Add new section to API documentation for a new feature |
170+
| Fix typo in README file |
171+
| Adding PHPDocs to methods in code |
172+
173+
⬆️ [Back to overview](#table)
174+
175+
#### <a name="feat"></a>Features ✨
176+
177+
**Type:** `feat`
178+
179+
Adding a **new feature** to the project.
180+
181+
| ✅ Use for | ❌ Don't use for |
182+
| -------------------------------------------------------- | -------------------------------------------------------- |
183+
| Add new search functionality to the website | Update API documentation with new features and endpoints |
184+
| Implement new payment processing system for checkout | Add new test cases for new feature |
185+
| Introduce new user profile page with additional features | Fixed bug on newly released feature |
186+
187+
⬆️ [Back to overview](#table)
188+
189+
#### <a name="fix"></a>Bug Fixes 🐛
190+
191+
**Type:** `fix`
192+
193+
Fix for a bug or issue in the project.
194+
195+
| ✅ Use for | ❌ Don't use for |
196+
| -------------------------------------------------------------------- | ------------------------------------------- |
197+
| Correct issue with login form validation not working | Adjust spacing and formatting of login page |
198+
| Resolve issue with images not loading in Internet Explorer | Simplify code for improved performance |
199+
| Fix bug causing application to crash when user clicks certain button |
200+
201+
⬆️ [Back to overview](#table)
202+
203+
#### <a name="perf"></a>Performance Improvements 🏎
204+
205+
**Type:** `perf`
206+
207+
A code change that **improves the performance** of the project.
208+
209+
| ✅ Use for | ❌ Don't use for |
210+
| ------------------------------------------------------ | ---------------- |
211+
| Optimize database queries to reduce page load times |
212+
| Improve rendering performance of complex UI elements |
213+
| Implement lazy loading of images to improve page speed |
214+
215+
⬆️ [Back to overview](#table)
216+
217+
#### <a name="refactor"></a>Code Refactoring ♻️
218+
219+
**Type:** `refactor`
220+
221+
A code change that neither fixes a bug nor adds a feature
222+
223+
| ✅ Use for | ❌ Don't use for |
224+
| ------------------------------------------------------ | ------------------------------------------------------------------------- |
225+
| Rename variables for improved clarity and consistency | Changed database query to improve load time |
226+
| Extract common code into a reusable function | Convert tabs to spaces in module A to follow project indentation standard |
227+
| Simplify complex logic to improve code readability |
228+
| Moved files to newly created directory for controllers |
229+
230+
⬆️ [Back to overview](#table)
231+
232+
#### <a name="revert"></a>Reverts ⏪️
233+
234+
**Type:** `revert`
235+
236+
Used to indicate that a previous commit is being undone or **reverted**.
237+
238+
| ✅ Use for | ❌ Don't use for |
239+
| ------------------------------------------- | --------------------------------- |
240+
| Revert "Add new feature to the application" | Changed logo to version from 2022 |
241+
| Undo changes made in commit 12345 |
242+
| Rollback changes to database schema |
243+
244+
⬆️ [Back to overview](#table)
245+
246+
#### <a name="style"></a>Styles 🎨
247+
248+
**Type:** `style`
249+
250+
Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
251+
252+
| ✅ Use for | ❌ Don't use for |
253+
| -------------------------------------------- | ---------------------------------------------------------------------- |
254+
| Format code according to project style guide | Change CSS of login page |
255+
| Remove trailing whitespace from files | Improved font size and style of website |
256+
| | Simplify logic in function A to make it more readable |
257+
| | Improve error handling in module D to be more robust and maintainable |
258+
| | Remove unnecessary dependencies from module F to simplify the codebase |
259+
260+
⬆️ [Back to overview](#table)
261+
262+
#### <a name="test"></a>Tests 🧪
263+
264+
**Type:** `test`
265+
266+
Indicate changes that add, modify, or remove **tests**.
267+
268+
| ✅ Use for | ❌ Don't use for |
269+
| ---------------------------------------------------- | ---------------------------------------- |
270+
| Add new unit test for module X | Test if new landing page converts better |
271+
| Modify existing integration test to cover edge cases |
272+
| Remove obsolete test cases for module Y |
273+
274+
⬆️ [Back to overview](#table)
275+
276+
#### <a name="wip"></a>Uncompleted Changes 🚧
277+
278+
**Type:** `wip`
279+
280+
Is used to indicate that a commit is a **work in progress** and is not yet complete. It is generally used when a developer wants to save their work-in-progress changes in a remote repository, such as GitHub, but is not ready to commit the changes with a more specific commit message.
281+
282+
It's important to note that wip is not a conventional commit type, but rather a shorthand way to indicate that a commit is a work in progress.
283+
284+
⬆️ [Back to overview](#table)
285+
286+
#### Initial commit
287+
288+
According to Gitmoji I suggest to use `Initial commit 🎉` as message for the first commit in a new repository without specifying a type or further information.
289+
290+
⬆️ [Back to overview](#table)
291+
292+
## Automatic setup with Git Hooks
293+
294+
It is possible to automatically add the emoji to the commit message by using the unique relationship between `type` and emoji. So it is possible to write "normal" conversional commits and they will be adjusted automatically.
295+
296+
In the following a client-side Git Hook will be created which will automatically add the correct emoji to the commit-message depending on the `type`. A Git hook is a script that Git can run before or after certain events occur, such as committing changes or pushing code to a remote repository. Git Hooks allow developers to automate certain tasks, enforce coding standards, and perform checks to ensure that code meets quality and security requirements.
297+
298+
To set up the git hook, all you need to do is copy the `commit-msg` file (check out the [source code](commit-msg)) from this repository and put it in the .git/hooks folder of the project in question and give the file the necessary permissions to run automatically. This can be done by the following command when executed in the project folder:
299+
300+
```
301+
curl https://raw.githubusercontent.com/eclipse313/conventional-commit-plus/main/commit-msg -o .git/hooks/commit-msg
302+
chmod +x .git/hooks/commit-msg
303+
```
304+
305+
See this hook in action. Pay attention to the added emoji after the commit message based on its `type`:
306+
307+
![Git Hook autocompletes emoji](assets/img/git-hook-demo.gif)
308+
309+
## Linting with Commitlint
310+
311+
Commitlint is a tool that helps enforce consistent commit message formatting in Git repositories. It provides a set of rules that can be used to ensure that commit messages follow a specific pattern and format. This helps improve the readability of the commit history and makes it easier to understand the changes that have been made to a project over time.
312+
313+
The nice thing is: the commit format with the final emoji from this repository is backwards compatible with the default settings of commitlint. If you want to learn more about commitlint check out their [website](https://commitlint.js.org/#/).
314+
315+
It is possible to configure commitlint to check whether the format described in the specification is followed. To do this, you need to add this repository to your dev dependencies:
316+
317+
```
318+
npm install --save-dev @eclipse313/conventional-commit-plus
319+
```
320+
321+
Then you need to edit your commitlint configuration so that the `extends` array includes this repository:
322+
323+
```
324+
// commitlint.config.js
325+
module.exports = {
326+
extends: ['@eclipse313/conventional-commit-plus'],
327+
};
328+
```
329+
330+
After installation, three new rules are available and automatically activated:
331+
332+
- **header-ends-with-emoji**: Checks if the header of the commit ends with an emoji.
333+
- **header-ends-with-allowed-emoji**: Checks if the header of the commit ends with one of the allowed emojis (see [types supported](#types-supported)).
334+
- **header-ends-with-matching-emoji**: Checks if the commit header ends with the emoji matching the type (see [types supported](#types-supported)).
335+
336+
See commitlint with this configuration in action:
337+
338+
![Commitlint checks](assets/img/commitlint.gif)
339+
340+
It is possible to disable and configure the rules as usual as described in the [commitlint documentation](https://commitlint.js.org/#/reference-rules):
341+
342+
```js
343+
rules: {
344+
"header-ends-with-emoji": [2, "always"],
345+
"header-ends-with-allowed-emoji": [1, "always"], // Set this rule to "warning"
346+
"header-ends-with-matching-emoji": [0, "always"], // Disable this rule
347+
}
348+
```
349+
350+
## Concluding remarks
351+
352+
I didn't think anyone would read this far. If you have any questions or suggestions, feel free to open issues in the repository. I appreciate feedback and suggestions for improvement.
353+
354+
– Thomas
355+
356+
[^1]: Rohrer, M. W.: Seeing is believing: the importance of visualization in manufacturing simulation. In: 2000 Winter Simulation Conference Proceedings (Cat. No.00CH37165). WSC 2000, Winter Simu- lation Conference, 10-13 Dec. 2000: IEEE, 2000, S. 1211–1216

‎assets/img/commitlint.gif‎

1.72 MB
Loading

‎assets/img/git-hook-demo.gif‎

470 KB
Loading

‎assets/img/github.png‎

79.6 KB
Loading

0 commit comments

Comments
 (0)