wip

Author: bearomorphism

docs/customization.md

@@ -207,7 +207,7 @@ cookiecutter gh:commitizen-tools/commitizen_cz_template
 
 See [commitizen_cz_template](https://github.com/commitizen-tools/commitizen_cz_template) for details.
 
-Once you publish your rules, you can send us a PR to the [Third-party section](./third-party-rules.md).
+Once you publish your rules, you can send us a PR to the [Third-party section](./third-party-plugins/about.md).
 
 ### Custom commit rules
 

docs/third-party-plugins/about.md

@@ -1,29 +1,60 @@
 # What are third-party plugins?
 
-Third-party plugins are a way to extend Commitizen with additional commit message rules.
+Third-party plugins are a way to extend Commitizen with additional customized features.
 
-They are available as PyPI packages (installable with `pip`).
+These plugins are available as PyPI packages (installable with `pip`).
 
 !!! note
     New plugins are welcome! Once you published your plugins, please send us a PR to update this page.
 
+!!! note "Historical notes"
+    This section was originally called "Third-Party Commitizen Templates", but has been renamed to "Third-Party Commitizen Rules" to better reflect the content.
 
-<!-- TODO: explain what are the different types of plugins -->
+## Plugin features
 
-## New plugin documentation template
+<!-- TODO: provide more details about the features -->
+
+### Commit message convention
+
+Includes the rules to validate and generate commit messages.
+
+### Version scheme
+
+Includes the rules to generate version numbers.
+
+### Version provider
+
+Read and write version from data sources.
+
+### Changelog format
+
+Generate changelog in customized formats.
 
-Please document what do they provide:
+## How do I create a new plugin?
+
+<!-- TODO -->
+
+## How to help us update the list of plugins?
+
+Please document what features the plugin provides:
 
 - a convention
 - a scheme
 - a provider
 - a `changelog_format`
 
-Of course, you can provide multiple features. `commitizen` itself is a plugin that provides all the features.
+Of course, a plugin can provide multiple features.
+You may have noticed that `commitizen` itself can be viewed as a plugin that provides all the above features.
+
+Please see [cz-path](./cz-path.md) for a detailed example.
+
+## New plugin documentation template
 
     # [Package name](https://github.com/author/package-name)
 
-    Description of the plugin.
+    <!-- Description of the plugin. -->
+
+    <!-- What features does the plugin provide? -->
 
     ## Installation
 
@@ -36,3 +67,7 @@ Of course, you can provide multiple features. `commitizen` itself is a plugin th
     ```sh
     cz --name package-name commit
     ```
+
+    ## Example
+
+    <!-- Example usage of the plugin. -->

docs/third-party-plugins/commitizen-deno-provider.md

@@ -0,0 +1,26 @@
+# [commitizen-deno-provider](https://pypi.org/project/commitizen-deno-provider/)
+
+A provider for **Deno** projects. The provider updates the version in deno.json and jsr.json files.
+
+## Installation
+
+```sh
+pip install commitizen-deno-provider
+```
+
+## Usage
+
+Add `deno-provider` to your configuration file.
+
+Example for `.cz.yaml`:
+
+```yaml
+---
+commitizen:
+  major_version_zero: true
+  name: cz_conventional_commits
+  tag_format: $version
+  update_changelog_on_bump: true
+  version_provider: deno-provider
+  version_scheme: semver
+```

docs/third-party-plugins/commitizen-emoji.md

@@ -0,0 +1,15 @@
+# [Commitizen emoji](https://pypi.org/project/commitizen-emoji/) (Unmaintained)
+
+Just like *conventional commit* format, but with emojis and optionally time spent and related tasks.
+
+## Installation
+
+```sh
+pip install commitizen-emoji
+```
+
+## Usage
+
+```sh
+cz --name cz_commitizen_emoji commit
+```

docs/third-party-plugins/conventional-jira.md

@@ -0,0 +1,11 @@
+# [Conventional JIRA](https://pypi.org/project/conventional-JIRA/)
+
+Just like _conventional commit_ format, but the scope has been restricted to a
+JIRA issue format, i.e. `project-issueNumber`. This standardises scopes in a
+meaningful way.
+
+## Installation
+
+```sh
+pip install conventional-JIRA
+```

docs/third-party-plugins/cz-conventional-gitmoji.md

@@ -0,0 +1,17 @@
+# [cz-conventional-gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji)
+
+*conventional commit*s, but with [gitmojis](https://gitmoji.dev).
+
+Includes a pre-commit hook that automatically adds the correct gitmoji to the commit message based on the conventional type.
+
+## Installation
+
+```sh
+pip install cz-conventional-gitmoji
+```
+
+## Usage
+
+```sh
+cz --name cz_gitmoji commit
+```

docs/third-party-plugins/cz-emoji.md

@@ -0,0 +1,15 @@
+# [cz-emoji](https://github.com/adam-grant-hendry/cz-emoji)
+
+_conventional commit_ format, but with emojis.
+
+## Installation
+
+```sh
+pip install cz-emoji
+```
+
+## Usage
+
+```sh
+cz --name cz_emoji commit
+```

docs/third-party-plugins/cz-legacy.md

@@ -0,0 +1,17 @@
+# [Conventional Legacy (cz_legacy)][cz_legacy]
+
+An extension of the *conventional commit* format to include user-specified
+legacy change types in the `CHANGELOG` while preventing the legacy change types
+from being used in new commit messages.
+
+## Installation
+
+```sh
+pip install cz_legacy
+```
+
+## Usage
+
+See the [Conventional Legacy README][cz_legacy] for instructions on configuration.
+
+[cz_legacy]: https://pypi.org/project/cz_legacy

docs/third-party-providers.md renamed to docs/third-party-plugins/cz-path.md

@@ -1,47 +1,18 @@
-Commitizen can read and write version from different sources. In addition to the native providers, some alternative version sources are available as PyPI packages (installable with `pip`).
-
-## [commitizen-deno-provider](https://pypi.org/project/commitizen-deno-provider/)
-
-A provider for **Deno** projects. The provider updates the version in deno.json and jsr.json files.
-
-### Installation
-
-```sh
-pip install commitizen-deno-provider
-```
-
-### Usage
-
-Add `deno-provider` to your configuration file.
-
-Example for `.cz.yaml`:
-
-```yaml
----
-commitizen:
-  major_version_zero: true
-  name: cz_conventional_commits
-  tag_format: $version
-  update_changelog_on_bump: true
-  version_provider: deno-provider
-  version_scheme: semver
-```
-
-## [cz-path](https://pypi.org/project/cz-path/)
+# [cz-path](https://pypi.org/project/cz-path/)
 
 Provides prefix choices for commit messages based on staged files (Git only).
 For example, if the staged files are `component/z/a.ts` and `component/z/b.ts`,
 the path prefix option will be `component/z` and commit message might look like:
 `component/z/: description of changes`. If only one file is staged, the extension
 is removed in the prefix.
 
-### Installation
+## Installation
 
 ```sh
 pip install cz-path
 ```
 
-### Usage
+## Usage
 
 Add `cz-path` to your configuration file.
 
@@ -59,7 +30,7 @@ Example for `.cz.json`:
 The default value for `remove_path_prefixes` is `["src"]`. Adding `/` to the
 prefixes is not required.
 
-### Example session
+## Example session
 
 ```plain
  $ git add .vscode/

docs/third-party-plugins/github-jira-conventional.md

@@ -0,0 +1,15 @@
+# [GitHub JIRA Conventional](https://pypi.org/project/cz-github-jira-conventional/)
+
+This plugin extends the Commitizen tools by:
+
+- requiring a JIRA issue ID in the commit message
+- creating links to GitHub commits in `CHANGELOG.md`
+- creating links to JIRA issues in `CHANGELOG.md`
+
+## Installation
+
+```sh
+pip install cz-github-jira-conventional
+```
+
+For installation instructions (configuration and pre-commit), please visit the [GitHub repository](https://github.com/apheris/cz-github-jira-conventional).