Skip to content

Commit 2e3c167

Browse files
lppeddlppedd
committed
docs: update readme
1 parent 8bd19c4 commit 2e3c167

File tree

1 file changed

+141
-159
lines changed

1 file changed

+141
-159
lines changed

‎README.md‎

Lines changed: 141 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,173 +1,155 @@
1-
<img align="left" width="85" height="85" src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_logo.png" alt="Plugin logo">
1+
<!--suppress HtmlDeprecatedAttribute, CheckImageSize -->
2+
<h1 align="center">
3+
<img align="center" width="80" src="./images/cc_logo.png" alt="Plugin logo">
4+
<span>Conventional Commit</span>
5+
</h1>
6+
<div align="center">
7+
<p>
8+
<span>Available at <a href="https://plugins.jetbrains.com/plugin/13389-conventional-commit">JetBrains Marketplace</a></span>
9+
<span>/</span>
10+
<a href="https://github.com/lppedd/idea-conventional-commit/releases">GitHub Releases</a>
11+
</p>
212

3-
# Conventional Commit
13+
[![build](https://img.shields.io/github/actions/workflow/status/lppedd/idea-conventional-commit/build.yml.svg?branch=master)](https://github.com/lppedd/idea-conventional-commit/actions/workflows/build.yml)
14+
[![idea](https://img.shields.io/badge/platform-2025.3-ff7700.svg?logo=intellij-idea)](https://www.jetbrains.com/idea/)
15+
[![kotlin](https://img.shields.io/badge/kotlin-2.2.21-blue.svg?logo=kotlin)](https://kotlinlang.org)
416

5-
### Available @ [JetBrains Plugins Repository][1]
17+
</div>
618

7-
Looking for the latest **plugin binaries**? Get them [here][2] as `.zip`
8-
<small>Supported IDE versions **from 0.26.0**: `253.17525` to `*` (all future releases)</small>
9-
<small>Supported IDE versions **from 0.25.0**: `233.11799` to `253.2`</small>
10-
<small>Supported IDE versions **from 0.24.0**: `233.11799` to `251.*`</small>
11-
<small>Supported IDE versions **from 0.23.0**: `223.4884` to `243.*`</small>
12-
<small>Supported IDE versions **from 0.19.0**: `202.6397` to `233.*`</small>
19+
## Overview
1320

14-
<strong>Additional Providers</strong> are available by installing other lightweight plugins.
21+
The **Conventional Commit** plugin provides completion support for [Conventional Commits][conventional-commits]
22+
(also known as semantic commits) in the IDE's VCS modal commit dialog and non-modal commit tool window.
1523

16-
| Context & GitHub | Plugins Repository | Type | Scope | Subject | Body | Footer type | Footer value |
17-
|-------------------|:--------------------------------------------:|:------------------:|:------------------:|:-------:|:----:|:-----------:|:------------:|
18-
| [Angular (2+)][6] | :heavy_check_mark: [Install][7] (Deprecated) | | :heavy_check_mark: | | | | |
19-
| [Commitlint][8] | :heavy_check_mark: [Install][9] (Deprecated) | :heavy_check_mark: | :heavy_check_mark: | | | | |
20-
| GitHub | Coming soon... | | | | | | |
21-
| VCS (extended) | Coming soon... | | | | | | |
24+
The plugin offers:
2225

23-
-----
26+
- **Standard completion** – context-aware suggestions.
27+
- **Template completion** – triggered on user demand.
28+
- **Extension API** – allowing additional providers for each part of a commit message:
29+
type, scope, subject, body, and footer.
2430

25-
The aim of this plugin is to provide completion for [conventional commits][3],
26-
also named _semantic_ commits, inside the VCS Commit dialog. The plugin must provide:
31+
Writing high-quality commit messages is essential for maintaining a clear and searchable project history.
2732

28-
- **standard completion** — based on context
29-
- **template completion** — initiated intentionally
30-
- **extensibility** — which means allowing attaching providers for the various parts of the commit:
31-
_type_, _scope_, _subject_, _body_ and _footer_
33+
The Conventional Commits specification is an excellent choice for this, as it also helps streamline
34+
the process of writing commits across teams. However, selecting the correct commit **type** or **scope**
35+
is not always straightforward. It is easy to forget when a particular **type** should be used,
36+
which **scopes** are available, or how to phrase a meaningful **subject**.
3237

33-
-----
38+
This plugin addresses these challenges while respecting the Conventional Commits
39+
[specification][conventional-commits-spec], allowing users to customize the experience
40+
to fit their own workflow and preferences.
3441

35-
Writing quality commit messages is important to keep an understandable and searchable history
36-
of your project. Conventional commits are a perfect example of that.
37-
However, as an example, it can happen choosing the correct _type_ or _scope_ isn't that immediate.
38-
We might have forgotten about when a specific _type_ should be used or what are the
39-
available _scopes_, or we simply need a way to quickly complete the _subject_.
42+
### IDE compatibility table
4043

41-
The plugin helps with the above, while also respecting the aforementioned requirements, so that
42-
each user is able to customize the experience based on its preferences.
44+
| From Plugin version | From Platform version | To Platform version |
45+
|---------------------|-----------------------|---------------------|
46+
| 0.26.0 | 253.17525 | * |
47+
| 0.25.0 | 233.11799 | 253.2* |
48+
| 0.24.0 | 233.11799 | 251.* |
49+
| 0.23.0 | 223.4884 | 243.* |
50+
| 0.19.0 | 202.6397 | 233.* |
4351

44-
### Completion modes
52+
## Completion modes
4553

4654
The plugin offers two completion modes.
47-
48-
- #### Context based
49-
The commit message can be written like you have done until now, but by invoking
50-
completion you'll be offered the correct items based on the scope.
51-
Certain commodities, such as auto-completing the scope parenthesis or the `:` separator,
52-
are there too.
53-
54-
<img src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_standard.gif" alt="Standard completion">
55-
56-
- #### Template based
57-
By firstly invoking the _type_ completion and confirming an item, a template will be
58-
generated in place, and you'll be guided through each token (_scope_ and _subject_).
59-
You can also go back (with `shift + tab`) and change your pick.
60-
61-
Arbitrary characters' insertion is also allowed inside each template's range marker.
62-
63-
<img src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_template.gif" alt="Template completion">
64-
65-
### Inspections
66-
67-
Inspections are bundled too, and they're **extensible**, which means a _Provider_ may contribute with
68-
additional ones.
69-
The standard inspection warns you if you're not following the Conventional Commit standard.
70-
In case, just press `ctrl + alt + l` (on Windows) and the commit message will be formatted for you.
71-
72-
<img src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_inspections.gif" alt="Inspections">
73-
74-
You may enable/disable inspections via _Settings > Version Control > Commit_
75-
76-
### Documentation
77-
78-
Each commit token is able to hold documentation. This is important in case you forgot their meaning
79-
or if you want to share additional pieces of information with users.
80-
81-
<img src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_docs.gif" alt="Documentation">
82-
83-
Documentation for tokens which might hold long text, spawning multiple lines, is rendered a bit differently.
84-
85-
<img width="840" height="281" src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_long_doc.png" alt="Long documentation">
86-
87-
### Custom default types and scopes
88-
89-
Default commit types and scopes can be totally customized and shared with your team by creating and populating
90-
a JSON file named
91-
```
92-
conventionalcommit.json
93-
```
94-
95-
The plugin uses an internal version of that file, which you can export via _Export built-in defaults to path_.
96-
You may then customize it per your needs.
97-
98-
<img width="840" height="572" src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_custom_defaults.png" alt="Custom defaults">
99-
100-
You're allowed to provide custom commit's _types_, _scopes_ and _footer types_, given the JSON file respects a [Schema][5].
101-
An example is shown below:
102-
103-
```json
104-
{
105-
"types": {
106-
"custom-type": {
107-
"description": "The custom type's description",
108-
"scopes": {
109-
"first": {
110-
"description": "The first scope's description"
111-
},
112-
"second": {}
113-
}
114-
}
115-
},
116-
"commonScopes": {
117-
"one": {
118-
"description": "The common scope's description"
119-
},
120-
"two": {}
121-
},
122-
"footerTypes": {
123-
"custom-footer": {
124-
"description": "The custom footer's description",
125-
"values": {
126-
"value-one": {
127-
"description": "The footer value's description"
128-
},
129-
"value-two": {}
130-
}
131-
}
132-
}
133-
}
134-
```
135-
136-
**If the file is located in the project's root directory, the plugin will pick it up automatically**,
137-
making it easy to version it and avoiding explicitly setting a _Custom default tokens_ path.
138-
139-
### Providers
140-
141-
In a fresh installation you'll only be offered the most common tokens (e.g. `fix`, `feat`, `build`, `BREAKING CHANGE`, etc.),
142-
but the plugin exposes an API to enhance completion items, per each token.
143-
_Type_, _scope_ and _subject_ each have a specific entry point, and the implementation is called
144-
**Provider**. Each Provider is listed in a table, based on its context.
145-
146-
<img width="845" height="552" src="https://raw.githubusercontent.com/lppedd/idea-conventional-commit/master/images/cc_providers.png" alt="Providers">
147-
148-
You're allowed to re-order Providers per your necessities, knowing that possible duplicates
149-
are going to be automatically filtered by the core engine.
150-
151-
<b>More on this later on...</b>
152-
153-
-----
154-
155-
## Author and contributors
156-
157-
- Edoardo Luppi (<[email protected]>)
158-
- [ymind][4]
159-
- [bric3][11]
160-
- [LinWanCen][12]
161-
162-
[1]: https://plugins.jetbrains.com/plugin/13389-conventional-commit
163-
[2]: https://github.com/lppedd/idea-conventional-commit/releases
164-
[3]: https://conventionalcommits.org/
165-
[4]: https://github.com/ymind
166-
[5]: https://github.com/lppedd/idea-conventional-commit/blob/master/src/main/resources/defaults/conventionalcommit.schema.json
167-
[6]: https://github.com/lppedd/idea-conventional-commit-angular2
168-
[7]: https://plugins.jetbrains.com/plugin/13405-angular-conventional-commit
169-
[8]: https://github.com/lppedd/idea-conventional-commit-commitlint
170-
[9]: https://plugins.jetbrains.com/plugin/14046-commitlint-conventional-commit
171-
[10]: https://join.slack.com/t/ideaconventio-1ts8697/shared_invite/zt-iuztsuth-pr_5wjvZGqITHCz3OOUxgQ
172-
[11]: https://github.com/bric3
173-
[12]: https://github.com/LinWanCen
55+
56+
### Context-based
57+
58+
The commit message can be written as usual. When you invoke code completion,
59+
you are offered the most appropriate suggestions based on the current context.
60+
61+
Several convenience features are included as well, such as automatically inserting
62+
the **scope** parentheses or the `:<space>` separator.
63+
64+
<img src="./images/cc_standard.gif" alt="Standard completion">
65+
66+
### Template-based
67+
68+
By first invoking completion for the commit **type** and selecting one of the suggested items,
69+
a commit message template is generated in place. You are then guided through each commit message
70+
token (**scope**, **subject**, **body**, **footer**).
71+
72+
You can move back to previous tokens using `SHIFT + TAB` (on Windows) to change selection.
73+
Instead of accepting a completion suggestion, an arbitrary value may also be typed directly
74+
inside each template range marker.
75+
76+
<img src="./images/cc_template.gif" alt="Template completion">
77+
78+
## Inspections
79+
80+
The plugin includes inspections that warn you whenever a commit message does not follow the
81+
Conventional Commits [specification][conventional-commits-spec]. If an issue is reported,
82+
simply use `CTRL + ALT + L` (on Windows) to automatically fix the commit message.
83+
84+
<img src="./images/cc_inspections.gif" alt="Inspections">
85+
86+
You can also provide your own inspections by registering implementations of `CommitInspectionProvider`
87+
from a dependant plugin.
88+
89+
### Toggling inspections
90+
91+
Commit message inspections can be enabled or disabled from **Settings > Version Control > Commit**.
92+
93+
## Token documentation
94+
95+
Each commit message token can include documentation, available through the usual Quick Documentation popup.
96+
This is useful whenever you are unsure about the meaning of a suggested item or whenever you are
97+
unsure whether that suggestion may be used in that particular context.
98+
99+
<img src="./images/cc_docs.gif" alt="Documentation">
100+
101+
Documentation for tokens that may span multiple lines is rendered slightly differently.
102+
103+
<img width="840" src="./images/cc_long_doc.png" alt="Long documentation">
104+
105+
## Custom tokens
106+
107+
Commit **types**, **scopes**, and **footers** can be customized and shared across your team
108+
by creating a file named `conventionalcommit.json` in the project's root directory, or by setting
109+
a file path via **Settings > Conventional Commit, Default tokens**.
110+
111+
The plugin bundles a predefined set of commonly used tokens, which you can export
112+
via the **Export built-in defaults to path...** action-link as a starting point.
113+
114+
<img width="840" src="./images/cc_custom_defaults.png" alt="Custom defaults">
115+
116+
The exported file can then be customized to suit your needs, as long as it conforms
117+
to the associated JSON [schema][schema].
118+
119+
If the file is located in the project's root directory, the plugin will pick it up automatically,
120+
making versioning easy and avoiding explicit file paths.
121+
122+
## Token providers
123+
124+
By default, a fresh installation offers only the most common tokens (e.g., `fix`, `feat`, `build`,
125+
`BREAKING CHANGE`, etc.).
126+
127+
However, the plugin exposes APIs to enhance completion suggestions for each commit message token,
128+
by registering implementations of:
129+
130+
- `CommitTypeProvider`
131+
- `CommitScopeProvider`
132+
- `CommitSubjectProvider`
133+
- `CommitBodyProvider`
134+
- `CommitFooterTypeProvider`
135+
- `CommitFooterValueProvider`
136+
137+
from dependant plugins.
138+
139+
Providers can also be reordered as needed via **Settings > Conventional Commit > Providers**,
140+
with duplicate suggestions automatically filtered out by the core engine.
141+
142+
<img width="845" src="./images/cc_providers.png" alt="Providers">
143+
144+
**More on this coming soon**.
145+
146+
## Author and Contributors
147+
148+
- [Edoardo Luppi](https://github.com/lppedd)
149+
- [ymind](https://github.com/ymind)
150+
- [bric3](https://github.com/bric3)
151+
- [LinWanCen](https://github.com/LinWanCen)
152+
153+
[conventional-commits]: https://conventionalcommits.org/
154+
[conventional-commits-spec]: https://www.conventionalcommits.org/en/v1.0.0/#specification
155+
[schema]: https://github.com/lppedd/idea-conventional-commit/blob/master/src/main/resources/defaults/conventionalcommit.schema.json

0 commit comments

Comments
 (0)