docs: Add docs for commit convention. (#222)

serious-scaffold · Oct 27, 2023 · 034e93d · 034e93d
1 parent fed3045
commit 034e93d
Show file tree

Hide file tree

Showing 8 changed files with 166 additions and 14 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -19,6 +19,7 @@
     "automodule",
     "cobertura",
     "deepclean",
+    "deflist",
     "elif",
     "endmacro",
     "epub",
@@ -40,9 +41,12 @@
     "Quickstart",
     "setuptools",
     "softprops",
+    "sphinxcontrib",
     "toctree",
+    "togglebutton",
     "typer",
-    "unshallow"
+    "unshallow",
+    "viewcode"
   ],
   "editor.codeActionsOnSave": {
     "source.fixAll": true
@@ -67,7 +71,10 @@
   "files.insertFinalNewline": true,
   "files.trimFinalNewlines": true,
   "files.trimTrailingWhitespace": true,
-  "markdown-preview-enhanced.breakOnSingleNewLine": false,
+  "myst.preview.extensions": [
+    "dollarmath",
+    "deflist"
+  ],
   "sortJSON.contextMenu": {
     "sortJSONAlphaNum": false,
     "sortJSONAlphaNumReverse": false,

diff --git a/docs/conf.py b/docs/conf.py
@@ -6,7 +6,7 @@
 
 from importlib import metadata
 
-# -- Project information -----------------------------------------------------
+# -- Project information ---------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 author = "huxuan"
@@ -16,7 +16,7 @@
 version = ".".join(release.split(".")[:2])
 
 
-# -- General configuration ---------------------------------------------------
+# -- General configuration -------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
@@ -42,20 +42,28 @@
     ),
 }
 
-# -- Options for HTML output -------------------------------------------------
+# -- Options for HTML output -----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
 html_static_path = ["_static"]
 
-# -- Options for autodoc extension  ------------------------------------------
+# -- Options for autodoc extension  ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 
 autodoc_default_options = {
     "members": None,
 }
 
-# -- Options for autodoc_pydantic extension  ---------------------------------
+# -- Options for autodoc_pydantic extension  -------------------------------------------
 # https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html
 
 autodoc_pydantic_settings_show_json = False
+
+# -- Options for myst-parser extension  ------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+myst_enable_extensions = [
+    "deflist",
+]
+myst_heading_anchors = 3
diff --git a/docs/dev/commit.md b/docs/dev/commit.md
@@ -0,0 +1,60 @@
+# Commit Convention
+
+Using structured commit messages, we can enhance the readability of our project history, simplify automated changelog generation, and streamline the release process. We primarily follow the [Conventional Commit](https://www.conventionalcommits.org/) and [Angular's commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits).
+
+## Commit Message Pattern
+
+```text
+<type>(<optional scope>): <description>
+```
+
+Examples:
+
+```text
+build(requirements): bump the prod group with 9 updates.
+docs: Add docs for commit convention.
+chore: remove deprecated key in ruff config.
+```
+
+Type
+: Describes the nature of the change:
+
+| Type      | Description                                            |
+|-----------|--------------------------------------------------------|
+| `build`   | Changes that affect the build system or dependencies.  |
+| `chore`   | Routine tasks or changes outside the src/runtime code. |
+| `ci`      | Changes related to continuous integration.             |
+| `docs`    | Documentation changes.                                 |
+| `feat`    | New features.                                          |
+| `fix`     | Bug fixes.                                             |
+| `perf`    | Performance improvements.                              |
+| `refactor`| Code restructuring without changing behavior.          |
+| `revert`  | Revert a previous commit.                              |
+| `style`   | Code formatting changes.                               |
+| `test`    | Add or update tests.                                   |
+
+Scope [Optional]
+: Represents the part of the project impacted by the change. Examples include `logging`, `settings`, and `cli`.
+
+### Breaking Change
+
+A "breaking change" refers to any modification that disrupts the existing functionality in a way that may affect users. It can be denoted using an exclamation mark (`!`) before the colon, like `refactor!: Stuff`.
+
+```{note}
+For more details, please refer to [the Angular convention](https://pawamoy.github.io/git-changelog/usage/#angularkarma-convention) and [the Conventional Commit convention](https://pawamoy.github.io/git-changelog/usage/#conventional-commit-convention) described in the documentation of `git-changelog`.
+```
+
+## Commit in Development Branches
+
+While the commit convention seems strict, we aim for flexibility during the development phase.
+By adhering to the [project configuration](proj.md#project-configuration), all changes should be introduced via pull/merge requests.
+Using the squash merge strategy, the emphasis is primarily on the title of pull/merge requests.
+In this way, individual commit within development branches does not need to strictly adhere to the commit convention.
+
+````{note}
+A CI/CD pipeline checks the titles of pull/merge requests against the following regex pattern:
+
+```text
+^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!?:\s.*
+```
+````
diff --git a/docs/dev/index.md b/docs/dev/index.md
@@ -4,4 +4,5 @@
 :maxdepth: 1
 proj
 env
+commit
 ```
diff --git a/template/.vscode/settings.json b/template/.vscode/settings.json
@@ -19,6 +19,7 @@
     "automodule",
     "cobertura",
     "deepclean",
+    "deflist",
     "elif",
     "endmacro",
     "epub",
@@ -40,9 +41,12 @@
     "Quickstart",
     "setuptools",
     "softprops",
+    "sphinxcontrib",
     "toctree",
+    "togglebutton",
     "typer",
-    "unshallow"
+    "unshallow",
+    "viewcode"
   ],
   "editor.codeActionsOnSave": {
     "source.fixAll": true
@@ -67,7 +71,10 @@
   "files.insertFinalNewline": true,
   "files.trimFinalNewlines": true,
   "files.trimTrailingWhitespace": true,
-  "markdown-preview-enhanced.breakOnSingleNewLine": false,
+  "myst.preview.extensions": [
+    "dollarmath",
+    "deflist"
+  ],
   "sortJSON.contextMenu": {
     "sortJSONAlphaNum": false,
     "sortJSONAlphaNumReverse": false,

diff --git a/template/docs/conf.py.jinja b/template/docs/conf.py.jinja
@@ -6,7 +6,7 @@ https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 from importlib import metadata
 
-# -- Project information -----------------------------------------------------
+# -- Project information ---------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 author = "{{ author_name }}"
@@ -16,7 +16,7 @@ release = metadata.version("{{ package_name }}")
 version = ".".join(release.split(".")[:2])
 
 
-# -- General configuration ---------------------------------------------------
+# -- General configuration -------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
@@ -46,20 +46,28 @@ html_theme_options = {
     ),
 }
 
-# -- Options for HTML output -------------------------------------------------
+# -- Options for HTML output -----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
 html_static_path = ["_static"]
 
-# -- Options for autodoc extension  ------------------------------------------
+# -- Options for autodoc extension  ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 
 autodoc_default_options = {
     "members": None,
 }
 
-# -- Options for autodoc_pydantic extension  ---------------------------------
+# -- Options for autodoc_pydantic extension  -------------------------------------------
 # https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html
 
 autodoc_pydantic_settings_show_json = False
+
+# -- Options for myst-parser extension  ------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+myst_enable_extensions = [
+    "deflist",
+]
+myst_heading_anchors = 3
diff --git a/template/docs/dev/commit.md b/template/docs/dev/commit.md
@@ -0,0 +1,60 @@
+# Commit Convention
+
+Using structured commit messages, we can enhance the readability of our project history, simplify automated changelog generation, and streamline the release process. We primarily follow the [Conventional Commit](https://www.conventionalcommits.org/) and [Angular's commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits).
+
+## Commit Message Pattern
+
+```text
+<type>(<optional scope>): <description>
+```
+
+Examples:
+
+```text
+build(requirements): bump the prod group with 9 updates.
+docs: Add docs for commit convention.
+chore: remove deprecated key in ruff config.
+```
+
+Type
+: Describes the nature of the change:
+
+| Type      | Description                                            |
+|-----------|--------------------------------------------------------|
+| `build`   | Changes that affect the build system or dependencies.  |
+| `chore`   | Routine tasks or changes outside the src/runtime code. |
+| `ci`      | Changes related to continuous integration.             |
+| `docs`    | Documentation changes.                                 |
+| `feat`    | New features.                                          |
+| `fix`     | Bug fixes.                                             |
+| `perf`    | Performance improvements.                              |
+| `refactor`| Code restructuring without changing behavior.          |
+| `revert`  | Revert a previous commit.                              |
+| `style`   | Code formatting changes.                               |
+| `test`    | Add or update tests.                                   |
+
+Scope [Optional]
+: Represents the part of the project impacted by the change. Examples include `logging`, `settings`, and `cli`.
+
+### Breaking Change
+
+A "breaking change" refers to any modification that disrupts the existing functionality in a way that may affect users. It can be denoted using an exclamation mark (`!`) before the colon, like `refactor!: Stuff`.
+
+```{note}
+For more details, please refer to [the Angular convention](https://pawamoy.github.io/git-changelog/usage/#angularkarma-convention) and [the Conventional Commit convention](https://pawamoy.github.io/git-changelog/usage/#conventional-commit-convention) described in the documentation of `git-changelog`.
+```
+
+## Commit in Development Branches
+
+While the commit convention seems strict, we aim for flexibility during the development phase.
+By adhering to the [project configuration](proj.md#project-configuration), all changes should be introduced via pull/merge requests.
+Using the squash merge strategy, the emphasis is primarily on the title of pull/merge requests.
+In this way, individual commit within development branches does not need to strictly adhere to the commit convention.
+
+````{note}
+A CI/CD pipeline checks the titles of pull/merge requests against the following regex pattern:
+
+```text
+^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!?:\s.*
+```
+````
diff --git a/template/docs/dev/index.md b/template/docs/dev/index.md
@@ -4,4 +4,5 @@
 :maxdepth: 1
 proj
 env
+commit
 ```