|
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> |
2 | 12 |
|
3 | | -# Conventional Commit |
| 13 | +[](https://github.com/lppedd/idea-conventional-commit/actions/workflows/build.yml) |
| 14 | +[](https://www.jetbrains.com/idea/) |
| 15 | +[](https://kotlinlang.org) |
4 | 16 |
|
5 | | -### Available @ [JetBrains Plugins Repository][1] |
| 17 | +</div> |
6 | 18 |
|
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 |
13 | 20 |
|
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. |
15 | 23 |
|
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: |
22 | 25 |
|
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. |
24 | 30 |
|
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. |
27 | 32 |
|
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. However, selecting the correct commit type or scope is not always |
| 35 | +straightforward. It is easy to forget when a particular type should be used, which scopes are available, |
| 36 | +or how to phrase a meaningful subject. |
32 | 37 |
|
33 | | ------ |
| 38 | +This plugin addresses these challenges while respecting the Conventional Commits specification, |
| 39 | +allowing users to customize the experience to fit their own workflow and preferences. |
34 | 40 |
|
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_. |
| 41 | +### Compatibility table |
40 | 42 |
|
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. |
| 43 | +| From Plugin version | From Platform version | To Platform version | |
| 44 | +|---------------------|-----------------------|---------------------| |
| 45 | +| 0.26.0 | 253.17525 | * | |
| 46 | +| 0.25.0 | 233.11799 | 253.2* | |
| 47 | +| 0.24.0 | 233.11799 | 251.* | |
| 48 | +| 0.23.0 | 223.4884 | 243.* | |
| 49 | +| 0.19.0 | 202.6397 | 233.* | |
43 | 50 |
|
44 | | -### Completion modes |
| 51 | +## Completion modes |
45 | 52 |
|
46 | 53 | 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 |
| 54 | + |
| 55 | +### Context-based |
| 56 | + |
| 57 | +The commit message can be written as usual. When you invoke code completion, |
| 58 | +you are offered the most appropriate suggestions based on the current context. |
| 59 | + |
| 60 | +Several convenience features are included as well, such as automatically inserting |
| 61 | +the **scope** parentheses or the `:<space>` separator. |
| 62 | + |
| 63 | +<img src="./images/cc_standard.gif" alt="Standard completion"> |
| 64 | + |
| 65 | +### Template-based |
| 66 | + |
| 67 | +By first invoking completion for the commit **type** and selecting one of the suggested items, |
| 68 | +a commit message template is generated in place. You are then guided through each message token |
| 69 | +(**scope**, **subject**, **footer**, etc.). |
| 70 | + |
| 71 | +You can move back to previous tokens (using `SHIFT + TAB`, on Windows) to change previous selections. |
| 72 | +Instead of accepting a suggestion, an arbitrary value may be typed directly inside each template |
| 73 | +range marker. |
| 74 | + |
| 75 | +<img src="./images/cc_template.gif" alt="Template completion"> |
| 76 | + |
| 77 | +## Inspections |
| 78 | + |
| 79 | +The plugin includes commit inspections that warn you whenever a commit message does not follow |
| 80 | +the Conventional Commits specification. When an issue is detected, you can use `CTRL + ALT + L` |
| 81 | +(on Windows) to automatically fix the commit message. |
| 82 | + |
| 83 | +<img src="./images/cc_inspections.gif" alt="Inspections"> |
| 84 | + |
| 85 | +You can also provide your own inspections by registering implementations of `CommitInspectionProvider` |
| 86 | +from a dependant plugin. |
| 87 | + |
| 88 | +### Toggling inspections |
| 89 | + |
| 90 | +Commit inspections can be enabled or disabled from **Settings > Version Control > Commit**. |
| 91 | + |
| 92 | +## Documentation |
| 93 | + |
| 94 | +Each commit token can include documentation, available through the usual Quick Documentation popup. |
| 95 | +This is useful whenever you are unsure about the meaning of a suggested token or whenever you are |
| 96 | +unsure whether the suggestion may be used in that particular context. |
| 97 | + |
| 98 | +<img src="./images/cc_docs.gif" alt="Documentation"> |
| 99 | + |
| 100 | +Documentation for tokens that may span multiple lines is rendered slightly differently. |
| 101 | + |
| 102 | +<img width="840" src="./images/cc_long_doc.png" alt="Long documentation"> |
| 103 | + |
| 104 | +## Custom commit tokens |
| 105 | + |
| 106 | +Commit **types**, **scopes**, and **footers** can be customized and shared across your team |
| 107 | +by creating a file named `conventionalcommit.json` in the project's root directory, or by setting |
| 108 | +a file path via **Settings > Conventional Commit, Default tokens**. |
| 109 | + |
| 110 | +The plugin bundles a predefined set of commonly used tokens, which you can export |
| 111 | +via the **Export built-in defaults to path** action link as a starting point. |
| 112 | + |
| 113 | +<img width="840" src="./images/cc_custom_defaults.png" alt="Custom defaults"> |
| 114 | + |
| 115 | +The exported file can then be customized to suit your needs, as long as it conforms |
| 116 | +to the associated JSON [schema][schema]. |
| 117 | + |
| 118 | +If the file is located in the project's root directory, the plugin will pick it up automatically, |
| 119 | +making versioning easy and avoiding explicit file paths. |
| 120 | + |
| 121 | +## Token Providers |
| 122 | + |
| 123 | +By default, a fresh installation offers only the most common tokens (e.g., `fix`, `feat`, `build`, |
| 124 | +`BREAKING CHANGE`, etc.). |
| 125 | + |
| 126 | +However, the plugin exposes APIs to enhance completion suggestions for each commit message token, |
| 127 | +by registering implementations of: |
| 128 | + |
| 129 | +- `CommitTypeProvider` |
| 130 | +- `CommitScopeProvider` |
| 131 | +- `CommitSubjectProvider` |
| 132 | +- `CommitBodyProvider` |
| 133 | +- `CommitFooterTypeProvider` |
| 134 | +- `CommitFooterValueProvider` |
| 135 | + |
| 136 | +from dependant plugins. |
| 137 | + |
| 138 | +Providers can be reordered as needed via **Settings > Conventional Commit > Providers**, |
| 139 | +with duplicate suggestions automatically filtered out by the core engine. |
| 140 | + |
| 141 | +<img width="845" src="./images/cc_providers.png" alt="Providers"> |
| 142 | + |
| 143 | +**More on this coming soon**. |
| 144 | + |
| 145 | +## Author and Contributors |
| 146 | + |
| 147 | +- [Edoardo Luppi](https://github.com/lppedd) |
| 148 | +- [ymind](https://github.com/ymind) |
| 149 | +- [bric3](https://github.com/bric3) |
| 150 | +- [LinWanCen](https://github.com/LinWanCen) |
| 151 | + |
| 152 | +[conventional-commits]: https://conventionalcommits.org/ |
| 153 | +[schema]: https://github.com/lppedd/idea-conventional-commit/blob/master/src/main/resources/defaults/conventionalcommit.schema.json |
0 commit comments