docs: reconcile version history

[Thomo1318]

User description

Cleanup TASKS.md and VERSION_HISTORY.md

---

PR Type

Documentation, Enhancement

---

Description

• Reorganized documentation into centralized docs/ directory with guides and references

• Simplified root README.md to focus on key features and navigation to sub-guides

• Streamlined TASKS.md roadmap with clearer version milestones and completion status

• Enhanced configuration with Conventional Commits template, delta pager, and versioning aliases

• Added linting tools (codespell, ruff, trivy) and commitlint configuration

---

Diagram Walkthrough

flowchart LR
  A["Root README.md"] -->|simplified| B["Navigation Hub"]
  B -->|points to| C["docs/guides/"]
  C -->|contains| D["setup.md"]
  C -->|contains| E["usage.md"]
  C -->|contains| F["contributing.md"]
  B -->|points to| G["docs/reference/"]
  G -->|contains| H["aliases.md"]
  I["TASKS.md"] -->|refactored| J["Cleaner Roadmap"]
  J -->|v3.0-v4.0| K["Future Versions"]
  L["config.toml"] -->|enhanced| M["Conventional Commits"]
  L -->|enhanced| N["Delta Pager"]
  L -->|enhanced| O["Versioning Aliases"]
  P[".trunk/trunk.yaml"] -->|added| Q["codespell, ruff, trivy"]
  R["commitlint.config.js"] -->|new| S["Commit Validation"]

Loading

File Walkthrough

	Relevant files
Configuration changes	2 files commitlint.config.js Add commitlint configuration for commit validation              +3/-0      trunk.yaml Add security and code quality linting tools                            +5/-1
Documentation	8 files publish-change.md Update release tag creation with automated versioning        +9/-2      README.md Simplify and reorganize documentation structure                    +33/-287 TASKS.md Refactor roadmap with clearer version milestones                  +41/-302 VERSION_HISTORY.md Add v3.0.0 and v1.2.1 release entries                                        +25/-0    audit-log.md Document fragmentation issues and consolidation plan          +68/-0    contributing.md Update links and improve Conventional Commits guidance      +26/-8    setup.md Update navigation links to new documentation structure      +10/-2    usage.md Create comprehensive user guide with workflows and integrations +156/-0
Enhancement	1 files config.toml Add Conventional Commits template and versioning aliases  +89/-11
Additional files	3 files gh-cli-analysis.md [link]    gh-cli-integration.md [link]    aliases.md [link]

---

Summary by CodeRabbit

• New Features

  • Automated release tag creation with version validation
  • New versioning commands (semver, patch, minor, major)
  • Commit message template support

• Documentation

  • Restructured documentation with centralised navigation hub
  • New setup and usage guides for streamlined onboarding
  • Enhanced contributing guide with workflow details
  • Comprehensive documentation audit and improvement roadmap

• Chores

  • Updated code quality and security linting tools
  • Conventional commits configuration enabled
  • Enhanced configuration with improved diff display

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This pull request centralises documentation architecture, automates release workflows with version validation, enhances tooling configuration (Trunk linters, commitlint, Jujutsu aliases), and expands semantic versioning commands. Changes span documentation guides, configuration updates, and workflow automation scripts.

Changes

Cohort / File(s)	Summary
Workflow Automation .agent/workflows/publish-change.md	Replaces manual release tag creation with automated two-part flow: dry-run version check via jj next-minor, then gh release create with generated notes.
Tooling & Linting .trunk/trunk.yaml, commitlint.config.js	Adds codespell@2.2.6 and trivy@0.48.1 linters; replaces shellcheck@0.11.0 with ruff@0.1.6; introduces commitlint config extending conventional commits standard.
Jujutsu Configuration config.toml	Refactors repomix and security commands to array-based syntax; switches UI pager to delta-based formatting; adds draft_commit_description template; introduces semantic versioning command aliases (semver, next-patch, next-minor, next-major).
Documentation Architecture README.md, docs/architecture/audit-log.md	Reorganises README with centralised docs structure, consolidated Table of Contents, and redirected Quick Start/Setup links. Introduces comprehensive audit plan for documentation consolidation across three phases with immediate action items.
Documentation Guides docs/guides/contributing.md, docs/guides/setup.md, docs/guides/usage.md	Adds new usage guide covering workflows, integrations, and versioning. Updates contributing and setup guides with relative link references and Conventional Commits formatting guidance.
Project Records TASKS.md, backups/VERSION_HISTORY.md	Rebrands task tracking from pending items to milestone-oriented roadmap (v3.1.0–v4.0.0). Adds two new version history entries: v1.2.1-docs (documentation overhaul) and v3.0.0-conventional (conventional commits + Trunk optimisation).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: validate and fix publication workflow artifacts #7: Overlaps with versioning command implementations in config.toml and automated release workflow enhancements.

Suggested labels

Review effort 3/5

Poem

🐰 Hops through docs with springy cheer,
Automation blooms throughout the year!
Versioning tags now run so free,
Configuration squared in harmony—
A tidy codebase, neat and clear! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e7d7f17 and df17f2e.

📒 Files selected for processing (14)

• .agent/workflows/publish-change.md
• .trunk/trunk.yaml
• README.md
• TASKS.md
• backups/VERSION_HISTORY.md
• commitlint.config.js
• config.toml
• docs/architecture/audit-log.md
• docs/architecture/gh-cli-analysis.md
• docs/architecture/gh-cli-integration.md
• docs/guides/contributing.md
• docs/guides/setup.md
• docs/guides/usage.md
• docs/reference/aliases.md

---

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.}

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Incomplete documentation migration breaks key links The documentation refactoring is incomplete, as the main README.md now contains a broken link to docs/reference/aliases.md. The alias reference documentation needs to be migrated to this new location. Examples: README.md [35] - **[Aliases](docs/reference/aliases.md)**: Full list of custom commands. docs/reference/aliases.md [1] # Alias Configuration Reference Files Solution Walkthrough: Before: # In README.md ... ### ⚙️ Reference - **[Aliases](docs/reference/aliases.md)**: Full list of custom commands. ... # In docs/reference/aliases.md (This file is empty) After: # In README.md ... ### ⚙️ Reference - **[Aliases](docs/reference/aliases.md)**: Full list of custom commands. ... # In docs/reference/aliases.md # Alias Reference This document lists all custom aliases available in jjConfig. ## Workflow Aliases - `jj st`: Status - `jj ll`: Log last 20 commits - `jj d`: Diff ... (Content from old aliases/README.md migrated here) Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a critical flaw where the alias documentation link in README.md points to a newly created but empty file, breaking navigation. It misstates that the file was deleted, but the core issue of missing content is valid and significant.	Medium
General	Add missing repomix-status alias Add the missing repomix-status alias to config.toml, as it is referenced in the documentation but not defined in the configuration file. config.toml [390-403] repomix-tokens = [ "util", "exec", "--", "bash", "-c", ''' - if command -v repomix &> /dev/null; then - repomix --token-count-tree 50 . - else - echo "⚠️ repomix not installed. Install with: npm install -g repomix" - fi +if command -v repomix &> /dev/null; then + repomix --token-count-tree 50 . +else + echo "⚠️ repomix not installed. Install with: npm install -g repomix" +fi ''' ] +repomix-status = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' +if [ -f .repomix/repomix-latest.txt ]; then + echo "✓ Repomix initialized" +else + echo "⚠️ No repomix file found. Run: jj repomix-generate" +fi +''' +] + Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a missing alias that is referenced in the new documentation, and provides a correct implementation, thus fixing an inconsistency between the code and the docs.	Medium
	Remove duplicated documentation section Consolidate the two duplicated "Versioning (Automated)" sections in docs/guides/usage.md into a single, coherent section to remove redundancy and improve clarity. docs/guides/usage.md [101-152] -## 🏷️ Versioning (Automated) +## 🏷️ Versioning & Commits -We use `git-semver` to automatically calculate the next version based on Conventional Commits and tags. +This project uses `git-semver` and Conventional Commits for automated versioning and release management. -### Aliases +### Composing Commits + +When you run `jj describe`, `jjConfig` provides a strict template to help you follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +# <type>(<scope>): <description> +# Types: feat, fix, docs, style, refactor, perf, test, chore +``` + +Correctly formatted commits are essential for the versioning aliases to work. + +### Versioning Aliases | Command | Description | Example Output | | :-------------- | :---------------------- | :------------- | | `jj semver` | Show current version | `v1.2.0` | | `jj next-patch` | Show next patch version | `v1.2.1` | | `jj next-minor` | Show next minor version | `v1.3.0` | | `jj next-major` | Show next major version | `v2.0.0` | ### Release Workflow ```bash -# create a release with the correct version +# Create a release with the correct version gh release create $(jj next-minor) --generate-notes -## 🏷️ Versioning (Automated) -We use git-semver to automatically calculate the next version based on Conventional Commits and tags. -### Composing Commits -When you run jj describe, jjConfig provides a strict template to help you follow Conventional Commits: - -# <type>(<scope>): <description> -# Types: feat, fix, docs, style, refactor, perf, test, chore - -### Aliases - Command Description Example Output - jj semver Show current version v1.2.0 - jj next-patch Show next patch version v1.2.1 - jj next-minor Show next minor version v1.3.0 - jj next-major Show next major version v2.0.0 -### Release Workflow -bash -# create a release with the correct version -gh release create $(jj next-minor) --generate-notes - `[To ensure code accuracy, apply this suggestion manually]` <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: The suggestion correctly identifies a duplicated section in a new documentation file, and the proposed change merges the content, which improves readability and correctness. </details></details></td><td align=center>Low </td></tr><tr><td> <details><summary>Cache version tag in variable</summary> ___ **In <code>publish-change.md</code>, store the output of <code>jj next-minor</code> in a variable and reuse <br>it to prevent potential inconsistencies between checking the version and <br>creating the release.** [.agent/workflows/publish-change.md [54-58]](https://github.com/Thomo1318/jjConfig/pull/9/files#diff-1bf49552a71680c902596d52f9aed194b2c55002ab3fcc242188a490021b68cdR54-R58) ```diff # Dry run to check version -jj next-minor +VERSION=$(jj next-minor) +echo "Releasing version $VERSION" # Create release -gh release create $(jj next-minor) --generate-notes +gh release create "$VERSION" --generate-notes Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out a potential race condition and improves the script's robustness by storing the command output in a variable, ensuring the same version is used for both checking and creating the release.	Low
	More