docs: add v2.0.0 documentation

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -22,9 +22,8 @@ body:
   - type: textarea
     id: configuration
     attributes:
-      label: .commit-check.yml
-      description: (auto-rendered as yaml, no need for backticks)
-      placeholder: 'checks: ...'
-      render: yaml
+      label: commit-check.toml or cchk.toml
+      description: (auto-rendered as toml, no need for backticks)
+      render: toml
     validations:
       required: false

README.rst

@@ -36,6 +36,19 @@ Fully customizable with error messages and suggested commands, it ensures compli
 
 As an alternative to GitHub Enterprise `Metadata restrictions <https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions>`_ and Bitbucket's paid plugin `Yet Another Commit Checker <https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter>`_, Commit Check stands out by integrating DevOps principles and Infrastructure as Code (IaC).
 
+What’s New in v2.0.0
+-----------------------
+
+Version 2.0.0 is a major release featuring a new configuration format, a modernized architecture, and an improved user experience.
+
+**✨ Highlights**
+
+* TOML Configuration — Replaces ``.commit-check.yml`` with ``cchk.toml`` or ``commit-check.toml`` for clearer, more consistent syntax.
+* Simplified CLI & Hooks — Legacy pre-commit hooks and options removed for a cleaner interface.
+* New Validation Engine — Redesigned for better flexibility, performance, and maintainability.
+
+For the full list of updates and improvements, see the `What's New <https://commit-check.github.io/commit-check/what-is-new.html>`_ page.
+
 Configuration
 -------------
 

docs/_static/extra_css.css

@@ -7,5 +7,10 @@ thead {
 .md-header,
 .md-tabs,
 .md-nav--primary .md-nav__title[for="__drawer"] {
-  background-color: #4051b5;
+  background-color: #009485;
+}
+
+/* Fix table header visibility for both light and dark modes */
+.md-content table th {
+  color: var(--md-typeset-color) !important;
 }

docs/changelog.rst

@@ -0,0 +1,54 @@
+Changelog
+=========
+
+All **notable changes** to this project will be documented in this file.
+
+Full changelog available at `GitHub releases <https://github.com/commit-check/commit-check/releases>`_.
+
+v2.0.0 (2025-10-01)
+-------------------
+
+.. Attention::
+    This major release introduces significant architectural changes and breaking updates to commit-check. Please review carefully before upgrading.
+
+What's New
+~~~~~~~~~~
+
+* **TOML Configuration** — Replaces the old ``.commit-check.yml`` with ``cchk.toml`` or ``commit-check.toml`` for clearer syntax.
+* **Simplified CLI & Hooks** — Legacy pre-commit hooks and command-line options have been removed for a cleaner, more consistent interface.
+* **New Validation Engine** — The validation system has been completely redesigned around a new ValidationEngine to improve maintainability and flexibility.
+
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+Configuration Format:
+
+* ``.commit-check.yml`` has been replaced with ``cchk.toml`` or ``commit-check.toml``.
+* All YAML configurations must be migrated to TOML from this version onward.
+* See the `Migration Guide <migration.html>`_ for step-by-step instructions.
+
+Removed Pre-commit Hooks and CLI Options:
+
+* Several legacy hooks and command-line flags have been removed in favor of a simplified interface.
+* Removed hooks: ``check-commit-signoff``, ``check-merge-base``, ``check-imperative``.
+* Removed CLI options: ``--signoff``, ``--merge-base``, ``--imperative``.
+
+Module Removal:
+
+* The following legacy modules have been removed: ``author.py``, ``branch.py``, ``commit.py``, ``error.py``.
+
+Architecture Redesign:
+
+* The validation system has been completely restructured around the new ``ValidationEngine``, breaking compatibility with any code or integrations relying on the old module structure.
+
+See PR :pr:`280`
+
+v0.10.2 (2025-08-26)
+--------------------
+
+Last release before the big v2.0 changes.
+
+v0.1.0 (2022-11-02)
+--------------------
+
+Initial release of commit-check.

docs/conf.py

@@ -22,6 +22,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx_issues",
 ]
 
 autodoc_member_order = "bysource"
@@ -31,19 +32,25 @@
 
 default_role = "any"
 
+# -- Options for sphinx_issues --------------------------------------------------------
+issues_default_group_project = "commit-check/commit-check"
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_immaterial"
 html_static_path = ["_static"]
-html_logo = "_static/logo.jpg"
+# html_logo = "_static/logo.jpg" can not display well in blue background
 # html_favicon = "_static/favicon.ico"
 html_css_files = ["extra_css.css"]
 html_title = "Commit Check"
 
 html_theme_options = {
     "repo_url": "https://github.com/commit-check/commit-check",
     "repo_name": "commit-check",
+    "icon": {
+        "logo": "material/git",
+    },
     "palette": [
         {
             "media": "(prefers-color-scheme: light)",

docs/configuration.rst

@@ -1,20 +1,22 @@
 Configuration
 =============
 
-``commit-check`` configuration file support TOML format.
+``commit-check`` configuration files support the TOML format. See ``cchk.toml`` for an example configuration.
 
-See ``cchk.toml`` for an example configuration.
+.. tip::
+  **Default Behavior**
 
-**Default Behavior**: When no configuration file exists, commit-check uses sensible defaults with minimal restrictions.
-
-Only conventional commits format, subject capitalization, and imperative mood are enforced by default.
-
-No length limits, author restrictions, or rebase requirements are applied.
+  * When no configuration file exists, commit-check uses sensible defaults with minimal restrictions.
+  * Only conventional commits format, subject capitalization, and imperative mood are enforced by default.
+  * No length limits, author restrictions, or rebase requirements are applied.
 
 commit-check can be configured via a ``cchk.toml`` or ``commit-check.toml`` file.
 
 The file should be placed in the root of your repository.
 
+Example Configuration
+---------------------
+
 .. code-block:: toml
 
     [commit]
@@ -44,8 +46,7 @@ The file should be placed in the root of your repository.
     # require_rebase_target = "main"  # Optional - no rebase requirement by default
 
 
-
-options table description
+Options Table Description
 -------------------------
 
 .. list-table::
@@ -70,7 +71,7 @@ options table description
      - subject_imperative
      - bool
      - true
-     - Subject must be in imperative mood.
+     - Subject must be in imperative mood. Forms of verbs can be found at `imperatives.py <https://github.com/commit-check/commit-check/blob/main/commit_check/imperatives.py>`_
    * - commit
      - subject_max_length
      - int

docs/index.rst

@@ -4,7 +4,10 @@
    :hidden:
 
    self
+   what-is-new
    configuration
+   migration
+   changelog
 
 .. toctree::
    :hidden:

docs/migration.rst

@@ -0,0 +1,189 @@
+Migration Guide
+===============
+
+This guide helps you migrate from commit-check v1.x (YAML configuration) to v2.0+ (TOML configuration).
+
+Overview
+--------
+
+Version 2.0 introduces significant changes to commit-check:
+
+* **Configuration format**: ``.commit-check.yml`` → ``cchk.toml`` or ``commit-check.toml``
+* **Simplified architecture**: New validation engine with cleaner design
+* **Enhanced functionality**: Better error messages and more flexible configuration options
+
+Quick Migration Steps
+---------------------
+
+1. **Backup your existing configuration**:
+
+   .. code-block:: bash
+
+       cp .commit-check.yml .commit-check.yml.backup
+
+2. **Create new TOML configuration**:
+
+   .. code-block:: bash
+
+       touch cchk.toml  # or commit-check.toml
+
+3. **Convert YAML to TOML format** (see examples below)
+
+4. **Test the new configuration**:
+
+   .. code-block:: bash
+
+       commit-check --help
+       commit-check --message --branch --author-name --author-email --dry-run
+
+5. **Remove old YAML file**:
+
+   .. code-block:: bash
+
+       rm .commit-check.yml.backup  # after confirming everything works
+
+Configuration Format Changes
+----------------------------
+
+The configuration structure has changed from YAML to TOML format
+
+YAML (v1.x) vs TOML (v2.0+)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Old YAML format** (``.commit-check.yml``):
+
+.. code-block:: yaml
+
+    checks:
+    - check: message
+        regex: '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)'
+        error: "The commit message should be structured as follows:\n\n
+        <type>[optional scope]: <description>\n
+        [optional body]\n
+        [optional footer(s)]\n\n
+        More details please refer to https://www.conventionalcommits.org"
+        suggest: please check your commit message whether matches above regex
+
+    - check: branch
+        regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)
+        error: "Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/"
+        suggest: run command `git checkout -b type/branch_name`
+
+    - check: author_name
+        regex: ^[A-Za-zÀ-ÖØ-öø-ÿ\u0100-\u017F\u0180-\u024F ,.\'-]+$|.*(\[bot])
+        error: The committer name seems invalid
+        suggest: run command `git config user.name "Your Name"`
+
+    - check: author_email
+        regex: ^.+@.+$
+        error: The committer email seems invalid
+        suggest: run command `git config user.email yourname@example.com`
+
+    - check: commit_signoff
+        regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
+        error: Signed-off-by not found in latest commit
+        suggest: run command `git commit -m "conventional commit message" --signoff`
+
+    - check: merge_base
+        regex: main # it can be master, develop, devel etc based on your project.
+        error: Current branch is not rebased onto target branch
+        suggest: Please ensure your branch is rebased with the target branch
+
+    - check: imperative
+        regex: '' # Not used for imperative mood check
+        error: 'Commit message should use imperative mood (e.g., "Add feature" not "Added feature")'
+        suggest: 'Use imperative mood in commit message like "Add", "Fix", "Update", "Remove"'
+
+**New TOML format** (``cchk.toml`` or ``commit-check.toml``):
+
+.. code-block:: toml
+
+    [commit]
+    # https://www.conventionalcommits.org
+    conventional_commits = true
+    subject_capitalized = false
+    subject_imperative = true
+    subject_max_length = 80
+    subject_min_length = 5
+    allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "ci"]
+    allow_merge_commits = true
+    allow_revert_commits = true
+    allow_empty_commits = false
+    allow_fixup_commits = true
+    allow_wip_commits = false
+    require_body = false
+    require_signed_off_by = false
+    allow_authors = []
+    ignore_authors = ["dependabot[bot]", "copilot[bot]"]
+
+    [branch]
+    # https://conventional-branch.github.io/
+    conventional_branch = true
+    allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
+    require_rebase_target = "main"
+
+
+
+CLI Changes
+~~~~~~~~~~~
+
+The command-line interface has been simplified:
+
+**Old CLI** (v1.x):
+
+.. code-block:: bash
+
+    commit-check --config .commit-check.yml
+
+**New CLI** (v2.0+):
+
+.. code-block:: bash
+
+    commit-check --config cchk.toml  # or commit-check.toml
+    # Or use defaults (no config file needed)
+    commit-check --message --branch
+
+
+Troubleshooting
+---------------
+
+Common Issues
+~~~~~~~~~~~~~
+
+**Issue**: "Configuration file not found"
+
+**Solution**: Ensure your file is named ``cchk.toml`` or ``commit-check.toml`` and placed in the repository root.
+
+**Issue**: "Invalid TOML syntax"
+
+**Solution**: Use a TOML validator or check the syntax. Common issues include:
+
+* Missing quotes around strings
+* Incorrect boolean values (use ``true``/``false``, not ``True``/``False``)
+* Invalid array syntax
+
+**Issue**: "Validation rules not working as expected"
+
+**Solution**: Check the `Configuration Documentation <configuration.html>`_ for the correct option names and formats.
+
+Validation and Testing
+~~~~~~~~~~~~~~~~~~~~~~
+
+After migration, test your configuration:
+
+.. code-block:: bash
+
+    # Test commit message validation
+    echo "feat: test commit message" | commit-check --message
+
+    # Test branch validation
+    commit-check --branch
+
+    # Test with dry-run flag
+    commit-check --message --branch --author-name --author-email --dry-run
+
+Getting Help
+------------
+
+* **Documentation**: Check the `Configuration Guide <configuration.html>`_
+* **Issues**: Report problems on `GitHub Issues <https://github.com/commit-check/commit-check/issues>`_