docs: add v2.0.0 documentation

[shenxianpeng]

Summary by CodeRabbit

• Documentation

  • Added “What’s New in v2.0.0”, a full changelog, detailed migration guide from v1.x (YAML) to v2.0+ (TOML) with examples, and expanded configuration docs and navigation.

• Chores

  • Enabled issue-linking for docs, updated docs dependencies to include the issues extension, and adjusted issue templates to reference TOML configs.

• Style

  • Updated site header/navigation color and documentation icon.

[coderabbitai]

Walkthrough

Adds v2.0.0 documentation: README release notes, a “What’s New” page, migration guide, and changelog; expands configuration docs with TOML examples and defaults; updates docs index; enables sphinx_issues in Sphinx config and pyproject optional deps; updates site header color to #009485 and issue template to reference TOML. No runtime code changes.

Changes

Cohort / File(s)	Summary
Release docs / v2 rollout README.rst, docs/what-is-new.rst, docs/migration.rst, docs/changelog.rst, docs/index.rst	Add v2.0.0 release notes and pages: “What’s New”, migration guide (YAML → TOML) with examples, changelog entry, and insert pages into docs toctree/navigation.
Configuration docs docs/configuration.rst	Expand configuration documentation with TOML examples (e.g., cchk.toml / commit-check.toml), Default Behavior tip, Example Configuration block, rewording and heading adjustments, and updated option descriptions.
Sphinx / build config docs/conf.py, pyproject.toml	Add sphinx_issues to Sphinx extensions and to [project.optional-dependencies].docs; set issues_default_group_project = "commit-check/commit-check" and add icon entry to html_theme_options.
Issue template .github/ISSUE_TEMPLATE/bug-report.yml	Change configuration field rendering and labels from YAML to TOML (render: toml; label text updated to reference commit-check.toml / cchk.toml).
Site styling docs/_static/extra_css.css	Update header/navigation background color from #4051b5 to #009485; add rule to fix table header visibility (.md-content table th { color: var(--md-typeset-color) !important; }).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: update README.rst for v2 #288 — Overlapping documentation updates for the v2 release, including TOML examples and README/configuration changes.

Poem

I thump the docs with gentle glee,
New TOML trails for all to see.
Changelogs hop and guides alight,
Sphinx now points to issues bright.
I twitch my nose: v2 takes flight! 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title concisely and accurately highlights the primary change of adding v2.0.0 documentation across the project, aligning with the pull request content without unnecessary detail.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/add-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codspeed-hq]

CodSpeed Performance Report

Merging #289 will not alter performance

_{Comparing feature/add-docs (8b7b728) with main (41af6df)¹}

Summary

✅ 27 untouched
⏩ 85 skipped²

Footnotes

1. No successful run was found on main (565af1a) during the generation of this report, so 41af6df was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 85 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[coderabbitai]

Actionable comments posted: 12

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 565af1a and 26ec62a.

📒 Files selected for processing (8)

• README.rst (1 hunks)
• docs/changelog.rst (1 hunks)
• docs/conf.py (2 hunks)
• docs/configuration.rst (2 hunks)
• docs/index.rst (1 hunks)
• docs/migration.rst (1 hunks)
• docs/what-is-new.rst (1 hunks)
• pyproject.toml (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

docs/**

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Maintain Sphinx documentation under docs/ to build HTML docs with sphinx-build

Files:

• docs/migration.rst
• docs/configuration.rst
• docs/conf.py
• docs/what-is-new.rst
• docs/changelog.rst
• docs/index.rst

pyproject.toml

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Declare package metadata, dependencies, and console entry points for commit-check and cchk

Files:

• pyproject.toml

🧠 Learnings (1)

📚 Learning: 2025-10-03T10:28:06.753Z

Learnt from: CR
PR: commit-check/commit-check#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-10-03T10:28:06.753Z
Learning: Applies to pyproject.toml : Declare package metadata, dependencies, and console entry points for commit-check and cchk

Applied to files:

• docs/configuration.rst
• README.rst

🪛 GitHub Actions: main

docs/migration.rst

[warning] 16-16: Sphinx: Title underline too short.

---

[warning] 46-46: Sphinx: Title underline too short.

---

[warning] 128-128: Sphinx: Title underline too short.

---

[warning] 148-148: Sphinx: Title underline too short.

---

[warning] 170-170: Sphinx: Title underline too short.

---

[warning] 186-186: Sphinx: Title underline too short.

docs/what-is-new.rst

[warning] 115-115: Sphinx: Inline emphasis start-string without end-string.

---

[warning] 170-170: Sphinx: Title underline too short.

---

[warning] 181-181: Sphinx: Title underline too short.

---

[warning] 227-227: Sphinx: Title underline too short.

docs/changelog.rst

[warning] 47-47: Sphinx: Title underline too short.

---

[warning] 47-47: Sphinx: Title underline too short.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Run benchmarks

🔇 Additional comments (10)

pyproject.toml (1)

47-47: LGTM!

The addition of sphinx_issues to the docs dependencies aligns with the Sphinx configuration changes in docs/conf.py and enables issue/PR reference syntax throughout the documentation (e.g., :pr:280``).

README.rst (1)

39-51: LGTM!

The new "What's New in v2.0.0" section provides a clear, concise overview of the major release changes. The highlights effectively communicate the key improvements (TOML configuration, simplified CLI & hooks, new validation engine) and the link to the full documentation page enables users to learn more.

docs/conf.py (2)

25-25: LGTM!

The addition of sphinx_issues extension properly integrates issue/PR reference support into the documentation build.

---

35-36: LGTM!

The configuration correctly sets the default GitHub project for issue references, enabling shorthand syntax like :pr:280`` throughout the documentation.

docs/index.rst (1)

7-10: LGTM!

The new toctree entries properly integrate the v2.0.0 documentation (What's New, Migration Guide, Changelog) into the documentation navigation. The ordering provides a logical flow for users upgrading to v2.0.0.

docs/configuration.rst (4)

4-4: LGTM!

The reference to cchk.toml for an example configuration properly guides users to the actual configuration file in the repository.

---

6-11: LGTM!

The new "Default Behavior" tip effectively communicates the out-of-the-box behavior to users, clarifying that commit-check has sensible defaults and only minimal restrictions are enforced without a configuration file.

---

17-47: LGTM!

The "Example Configuration" section provides a comprehensive, well-commented TOML example that demonstrates all major configuration options. The inline comments effectively explain optional vs. required settings and the default values.

---

49-49: LGTM!

The section rename to "Options Table Description" improves clarity and follows standard documentation conventions.

docs/what-is-new.rst (1)

1-237: Overall documentation quality is excellent.

The "What's New" document provides comprehensive coverage of the v2.0.0 release, with clear explanations, helpful examples, and good cross-references to other documentation. The side-by-side comparisons of YAML vs TOML configurations are particularly valuable for users migrating from v1.x.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.94%. Comparing base (e3d141c) to head (8b7b728).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #289       +/-   ##
===========================================
- Coverage   97.80%   79.94%   -17.87%     
===========================================
  Files           8        8               
  Lines         365      673      +308     
===========================================
+ Hits          357      538      +181     
- Misses          8      135      +127     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3ba6050 and f138d8a.

📒 Files selected for processing (3)

• docs/_static/extra_css.css (1 hunks)
• docs/conf.py (2 hunks)
• docs/configuration.rst (3 hunks)

✅ Files skipped from review due to trivial changes (1)

• docs/_static/extra_css.css

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/conf.py

🧰 Additional context used

📓 Path-based instructions (1)

docs/**

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Maintain Sphinx documentation under docs/ to build HTML docs with sphinx-build

Files:

• docs/configuration.rst

🧠 Learnings (1)

📚 Learning: 2025-10-03T10:28:06.753Z

Learnt from: CR
PR: commit-check/commit-check#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-10-03T10:28:06.753Z
Learning: Applies to pyproject.toml : Declare package metadata, dependencies, and console entry points for commit-check and cchk

Applied to files:

• docs/configuration.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)

• GitHub Check: install (3.13, ubuntu-24.04)
• GitHub Check: install (3.12, ubuntu-24.04)
• GitHub Check: install (3.13, windows-latest)
• GitHub Check: install (3.10, ubuntu-24.04)
• GitHub Check: install (3.10, macos-latest)
• GitHub Check: install (3.11, windows-latest)
• GitHub Check: install (3.12, windows-latest)
• GitHub Check: install (3.10, windows-latest)
• GitHub Check: install (3.9, macos-latest)
• GitHub Check: install (3.9, ubuntu-24.04)
• GitHub Check: install (3.9, windows-latest)
• GitHub Check: Run benchmarks

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a9efbac and 8b7b728.

📒 Files selected for processing (1)

• docs/_static/extra_css.css (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Maintain Sphinx documentation under docs/ to build HTML docs with sphinx-build

Files:

• docs/_static/extra_css.css

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: install (3.12, windows-latest)
• GitHub Check: install (3.11, windows-latest)
• GitHub Check: install (3.10, windows-latest)
• GitHub Check: install (3.9, windows-latest)
• GitHub Check: Run benchmarks

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Restore sufficient header contrast

Setting the header background to #009485 drops white text contrast to ~3.4:1, below WCAG AA’s 4.5:1 minimum for normal navigation text. Please pick a darker shade or adjust the foreground color so the ratio meets 4.5:1 before landing this.

🤖 Prompt for AI Agents

In docs/_static/extra_css.css around lines 10–11, the header background color
(#009485) reduces white text contrast below WCAG AA; change the CSS so the
header background is a darker shade or the header text color is a sufficiently
darker foreground color such that the contrast ratio is at least 4.5:1, update
the CSS accordingly, and verify the new color pair with a contrast checker
before committing.