mvn-tree-visualizer 1.3.0__tar.gz → 1.5.0__tar.gz

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/.github/SECURITY.md

@@ -6,8 +6,9 @@ We actively support the following versions of mvn-tree-visualizer:
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 1.3.x   | :white_check_mark: |
 | 1.2.x   | :white_check_mark: |
-| 1.1.x   | :white_check_mark: |
+| 1.1.x   | :x:                |
 | 1.0.x   | :x:                |
 
 ## Reporting a Vulnerability

mvn_tree_visualizer-1.5.0/.github/copilot-instructions.md

@@ -0,0 +1,87 @@
+# Maven Dependency Tree Visualizer - AI Coding Agent Instructions
+
+## Architecture Overview
+
+This is a **command-line tool** that converts Maven dependency tree output into interactive HTML diagrams and JSON data. The tool follows a **pipeline architecture**:
+
+1. **Input Processing**: Merges multiple `maven_dependency_file` files from different Maven modules (`get_dependencies_in_one_file.py`)
+2. **Data Transformation**: Parses Maven tree format and converts to Mermaid diagram syntax (`diagram.py`, `outputs/html_output.py`)
+3. **Output Generation**: Creates themed HTML with interactive features or structured JSON (`outputs/`)
+4. **Watch Mode**: Real-time file monitoring for development workflows (`file_watcher.py`)
+
+## Key Components & Data Flow
+
+### Core Pipeline (`cli.py`)
+- Entry point validates inputs → merges dependency files → generates outputs
+- **Error handling is comprehensive** - uses custom exception hierarchy in `exceptions.py`
+- Supports both HTML (interactive) and JSON (programmatic) output formats
+
+### Multi-Module Maven Support (`get_dependencies_in_one_file.py`)
+- **Critical pattern**: Recursively finds and merges `maven_dependency_file` from all subdirectories
+- Maven projects often have complex module structures - tool handles this automatically
+- Generated intermediate file `dependency_tree.txt` is cleaned up unless `--keep-tree` is used
+
+### Mermaid.js Conversion (`outputs/html_output.py`)
+- **Node classification logic**: Root (blue), intermediate (orange), leaf (green) based on dependency relationships
+- **Sanitization pattern**: Maven artifact names → valid Mermaid node IDs (hyphens to underscores)
+- Tracks parent/child relationships to determine node types for consistent styling
+
+### Theme System (`themes.py`, `enhanced_template.py`)
+- **Consistent color scheme** across all themes via `STANDARD_COLORS`
+- Dark theme has specific text visibility fixes for Mermaid.js compatibility
+- Template includes pan/zoom, download functionality, keyboard shortcuts
+
+## Maven Integration Workflow
+
+The tool expects this Maven command to be run first:
+```bash
+mvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true
+```
+
+**Why this matters**: The tool is designed around Maven's specific output format and file placement in `target/` directories.
+
+## Development Conventions
+
+### Error Handling
+- Custom exception hierarchy: `MvnTreeVisualizerError` → specific error types
+- **Pattern**: Validate early, fail fast with helpful error messages including Maven commands
+- File operations wrapped with encoding and permission checks
+
+### Testing Patterns (`tests/`)
+- **Key test pattern**: Use temporary directories for file operations
+- Mock file system events for watch mode testing
+- Mermaid output validation focuses on relationships and styling classes
+
+### Code Organization
+- **Outputs as pluggable modules**: `outputs/html_output.py`, `outputs/json_output.py`
+- Validation logic centralized in `validation.py`
+- Theme configuration as data classes, not inheritance
+
+## Critical Implementation Details
+
+### Watch Mode (`file_watcher.py`)
+- Uses `watchdog` library with custom event handlers
+- Monitors for changes to any file named `maven_dependency_file` in directory tree
+- Callback-based architecture for diagram regeneration
+
+### Version Display Logic
+- `--show-versions` flag affects both HTML and JSON output
+- Version info stripped/included during Mermaid conversion, not at template level
+
+### File Path Handling
+- **Windows compatibility**: Uses `pathlib.Path` consistently
+- Intermediate files created in output directory, not temp
+- Directory creation is recursive (`parents=True, exist_ok=True`)
+
+## Common Debugging Workflows
+
+1. **No dependency files found**: Check if Maven command was run and generated files in `target/` dirs
+2. **Empty diagrams**: Verify Maven output format and encoding (UTF-8 expected)
+3. **Theme rendering issues**: Dark theme has specific CSS overrides for Mermaid.js text visibility
+4. **Watch mode not triggering**: Ensure file names match exactly (`maven_dependency_file`)
+
+## Extension Points
+
+- **New output formats**: Add modules to `outputs/` directory following existing pattern
+- **Custom themes**: Extend `THEMES` dict in `themes.py` with `Theme` objects
+- **New validation rules**: Add to `validation.py` following existing error patterns

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/.github/dependabot.yml

@@ -12,6 +12,19 @@ updates:
     labels:
       - "dependencies"
       - "python"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+    labels:
+      - "dependencies"
+      - "uv"
+      - "python"
   
   # Enable version updates for GitHub Actions
   - package-ecosystem: "github-actions"

mvn_tree_visualizer-1.5.0/.github/instructions/copilot-instructions.md

@@ -0,0 +1,92 @@
+# GitHub Copilot Instructions for mvn-tree-visualizer
+
+## Project Overview
+This is a Python CLI tool that parses Maven dependency trees (`mvn dependency:tree` output) and generates interactive HTML diagrams (using Mermaid.js) or JSON outputs. The tool supports watch mode for real-time regeneration and has a modular architecture focused on error handling and user experience.
+
+## Architecture & Key Components
+
+### Core Flow
+1. **Input Validation** (`validation.py`) - Find and validate Maven dependency files
+2. **File Merging** (`get_dependencies_in_one_file.py`) - Combine multiple dependency files
+3. **Parsing** (`diagram.py`) - Read merged dependency tree
+4. **Output Generation** (`outputs/`) - Generate HTML (Mermaid.js) or JSON
+5. **Watch Mode** (`file_watcher.py`) - Monitor files for changes using watchdog
+
+### Module Structure
+```
+src/mvn_tree_visualizer/
+├── cli.py              # Entry point with comprehensive error handling
+├── exceptions.py       # Custom exception hierarchy
+├── validation.py       # File discovery and validation logic
+├── diagram.py          # Core dependency tree processing
+├── file_watcher.py     # Real-time file monitoring
+├── get_dependencies... # Multi-file merging logic
+├── TEMPLATE.py         # Jinja2 HTML template for Mermaid.js
+└── outputs/
+    ├── html_output.py  # Mermaid diagram generation
+    └── json_output.py  # Structured JSON output
+```
+
+## Development Conventions
+
+### Error Handling Pattern
+- Use custom exceptions from `exceptions.py`: `DependencyFileNotFoundError`, `DependencyParsingError`, `OutputGenerationError`
+- Provide actionable error messages with Maven commands and file paths
+- Follow the pattern in `cli.py:generate_diagram()` for comprehensive error handling
+
+### Testing Approach
+- Use pytest with descriptive test names like `test_convert_to_mermaid_deeper_tree()`
+- Test both positive cases and error conditions
+- Include realistic Maven dependency tree samples in test data
+- Run tests with: `uv run pytest tests/ -v`
+
+### Package Management
+- Uses `uv` as package manager - always use `uv run` for commands
+- Core dependencies: `jinja2` (templating), `watchdog` (file monitoring)
+- Entry point: `mvn-tree-visualizer` command maps to `cli:cli`
+
+### Code Quality
+- Lint with: `uv run ruff check .`
+- Type hints required throughout (project uses Python 3.13+)
+- Follow existing patterns for file validation and path handling
+
+## Critical Implementation Details
+
+### Maven Dependency Parsing
+- Input format: `[INFO] groupId:artifactId:type:version:scope` with tree structure using `+`, `|`, `\`
+- Handle both 4-part and 5-part dependency strings (see `html_output.py:_convert_to_mermaid`)
+- Depth calculation based on whitespace: `depth = len(parts[0].split(" ")) - 1`
+
+### File Discovery Pattern
+- Multi-file support: searches directory tree for `maven_dependency_file` (configurable)
+- Merges files from different Maven modules into single intermediate file
+- Validates file existence, permissions, and content before processing
+
+### Output Generation
+- HTML uses Mermaid.js with `graph LR` format
+- Version display controlled by `--show-versions` flag
+- JSON output maintains tree structure with parent-child relationships
+
+### Watch Mode Implementation
+- Uses watchdog library for cross-platform file monitoring
+- Monitors specific filename pattern across directory tree
+- Debounces changes and provides timestamped feedback
+
+## Common Development Tasks
+
+### Adding New Output Formats
+1. Create new module in `outputs/` directory
+2. Follow pattern from `html_output.py` and `json_output.py`
+3. Add format option to CLI and update `generate_diagram()` in `cli.py`
+
+### Error Message Improvements
+- All user-facing errors should include specific file paths and suggested Maven commands
+- Use `print_maven_help()` pattern for guiding users to generate dependency files
+- Test error scenarios in addition to happy path
+
+### Testing New Features
+- Include realistic Maven dependency trees in test data
+- Test both single-module and multi-module project scenarios
+- Verify error handling with invalid/missing files
+
+Remember: This tool processes Maven output files, not Maven projects directly. Users must run `mvn dependency:tree -DoutputFile=maven_dependency_file` first.

mvn_tree_visualizer-1.5.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Semantic Release
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+      pull-requests: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+
+    - name: Install dependencies
+      run: |
+        uv sync --dev
+        
+    - name: Run tests
+      run: |
+        uv run pytest tests/ -v
+
+    - name: Run linting
+      run: |
+        uv run ruff check .
+
+    - name: Python Semantic Release
+      id: release
+      uses: python-semantic-release/python-semantic-release@v10.2.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Publish to PyPI
+      if: steps.release.outputs.released == 'true'
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        uv run twine upload dist/*

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/CHANGELOG.md

@@ -5,10 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-### Added
-- Placeholder for future features
+<!--next-version-placeholder-->
 
 ## [1.3.0] - 2025-07-09
 
@@ -48,6 +45,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Enhanced CLI help text to reflect new features
+- Improved JSON output structure for better programmatic access
+- Updated documentation with version feature examples
+
+### Fixed
+- Type annotation issues and improved code clarity
+- JSON serialization for complex dependency structures
+
+## [1.1.0] - 2025-07-05
+
+### Added
+- JSON output format option for programmatic consumption
+- Multi-file support for Maven modules (searches for multiple `maven_dependency_file`)
+- File merging functionality for complex projects
+- Comprehensive error handling for file operations
+- Enhanced CLI with format selection
+
+### Changed
+- Improved project structure with organized outputs directory
+- Better separation of concerns between HTML and JSON generation
+
+### Fixed
+- File handling issues with large dependency trees
+- Output format validation and error messages
+
+## [1.0.0] - 2025-07-01
+
+### Added
+- Initial release of mvn-tree-visualizer
+- HTML diagram generation using Mermaid.js
+- CLI interface for processing Maven dependency files
+- Basic error handling and validation
+- Support for Maven dependency tree parsing
+- Interactive HTML output with visual dependency graphs
 - Improved code documentation and readability with type hints
 - Updated README.md with new feature documentation and usage examples
 

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/CONTRIBUTING.md

@@ -47,8 +47,48 @@ pytest
 
 ### Commit and push
 
+We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages to enable automatic versioning and changelog generation.
+
+**Commit Message Format:**
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types:**
+- `feat`: A new feature (triggers minor version bump)
+- `fix`: A bug fix (triggers patch version bump)
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance (triggers patch version bump)
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Changes to the build process or auxiliary tools
+- `ci`: Changes to CI configuration files and scripts
+
+**Examples:**
+```bash
+feat: add theme support with --theme option
+fix: resolve dependency parsing error with special characters
+docs: update README with new theme examples
+chore: update dependencies to latest versions
+```
+
+**BREAKING CHANGES:**
+For breaking changes, add `!` after the type or include `BREAKING CHANGE:` in the footer:
+```bash
+feat!: change CLI interface for better usability
+# or
+feat: change CLI interface
+
+BREAKING CHANGE: --output-format flag renamed to --format
+```
+
 ```bash
-git commit -m "Your descriptive commit message"
+git commit -m "feat: add your new feature description"
 git push origin 123-add-a-feature
 ```
 

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mvn-tree-visualizer
-Version: 1.3.0
+Version: 1.5.0
 Summary: A simple command line tool to visualize the dependency tree of a Maven project in a graphical format.
 Project-URL: source, https://github.com/dyka3773/mvn-tree-visualizer
 Author-email: Iraklis Konsoulas <dyka3773@gmail.com>
@@ -55,12 +55,12 @@ pip install mvn-tree-visualizer
 - **🌐 Multiple Output Formats:**
   - **HTML:** Generates an interactive HTML diagram of your dependency tree using Mermaid.js.
   - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
+- **🎨 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
 - **🔄 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.
-- **📋 Version Display:** Show or hide dependency versions in both HTML and JSON outputs using the `--show-versions` flag.
-- **⚡ Easy to Use:** A simple command-line interface that gets the job done with minimal configuration.
-- **📂 File Merging:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
-- **🎨 Customizable Output:** Specify the output file name and location.
-- **💾 SVG Export:** Download the generated diagram as an SVG file directly from the HTML page.
+- **📋 Version Display:** Toggle dependency versions in outputs with `--show-versions`
+- **💾 Enhanced Downloads:** SVG and PNG export directly from browser
+- **📂 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
+- **🎯 Color Coding:** Visual distinction between root, intermediate, and leaf dependencies
 
 ## How to Use
 
@@ -93,6 +93,15 @@ mvn_tree_visualizer --filename "maven_dependency_file" --output "dependencies.js
 mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html" --show-versions
 ```
 
+#### With Custom Themes
+```bash
+# Dark theme for low-light environments  
+mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html" --theme dark
+
+# Default minimal theme (clean monospace design)
+mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html"
+```
+
 #### JSON Output with Versions
 ```bash
 mvn_tree_visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json --show-versions
@@ -129,12 +138,20 @@ Each example includes:
 | `--filename` | The name of the file containing the Maven dependency tree | `maven_dependency_file` |
 | `--output` | The name of the output file | `diagram.html` |
 | `--format` | The output format (`html` or `json`) | `html` |
+| `--theme` | Theme for HTML diagrams (`minimal`, `dark`) | `minimal` |
 | `--show-versions` | Show dependency versions in the diagram | `False` |
 | `--watch` | Watch for file changes and auto-regenerate diagram | `False` |
 | `--directory` | The directory to scan for the Maven dependency file(s) | current directory |
 | `--keep-tree` | Keep the intermediate `dependency_tree.txt` file | `False` |
 | `--help` | Show the help message and exit | - |
 
+### Theme Options
+
+- **`minimal`**: Clean monospace design with simple black borders (default)
+- **`dark`**: Same minimal styling but with white text on black background
+
+📖 **See the complete [Theme Documentation](docs/THEMES.md) for detailed information about themes and interactive features.**
+
 ## Performance
 
 **For Large Projects:**

{mvn_tree_visualizer-1.3.0 → mvn_tree_visualizer-1.5.0}/README.md

@@ -35,12 +35,12 @@ pip install mvn-tree-visualizer
 - **🌐 Multiple Output Formats:**
   - **HTML:** Generates an interactive HTML diagram of your dependency tree using Mermaid.js.
   - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
+- **🎨 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
 - **🔄 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.
-- **📋 Version Display:** Show or hide dependency versions in both HTML and JSON outputs using the `--show-versions` flag.
-- **⚡ Easy to Use:** A simple command-line interface that gets the job done with minimal configuration.
-- **📂 File Merging:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
-- **🎨 Customizable Output:** Specify the output file name and location.
-- **💾 SVG Export:** Download the generated diagram as an SVG file directly from the HTML page.
+- **📋 Version Display:** Toggle dependency versions in outputs with `--show-versions`
+- **💾 Enhanced Downloads:** SVG and PNG export directly from browser
+- **📂 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
+- **🎯 Color Coding:** Visual distinction between root, intermediate, and leaf dependencies
 
 ## How to Use
 
@@ -73,6 +73,15 @@ mvn_tree_visualizer --filename "maven_dependency_file" --output "dependencies.js
 mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html" --show-versions
 ```
 
+#### With Custom Themes
+```bash
+# Dark theme for low-light environments  
+mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html" --theme dark
+
+# Default minimal theme (clean monospace design)
+mvn_tree_visualizer --filename "maven_dependency_file" --output "diagram.html"
+```
+
 #### JSON Output with Versions
 ```bash
 mvn_tree_visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json --show-versions
@@ -109,12 +118,20 @@ Each example includes:
 | `--filename` | The name of the file containing the Maven dependency tree | `maven_dependency_file` |
 | `--output` | The name of the output file | `diagram.html` |
 | `--format` | The output format (`html` or `json`) | `html` |
+| `--theme` | Theme for HTML diagrams (`minimal`, `dark`) | `minimal` |
 | `--show-versions` | Show dependency versions in the diagram | `False` |
 | `--watch` | Watch for file changes and auto-regenerate diagram | `False` |
 | `--directory` | The directory to scan for the Maven dependency file(s) | current directory |
 | `--keep-tree` | Keep the intermediate `dependency_tree.txt` file | `False` |
 | `--help` | Show the help message and exit | - |
 
+### Theme Options
+
+- **`minimal`**: Clean monospace design with simple black borders (default)
+- **`dark`**: Same minimal styling but with white text on black background
+
+📖 **See the complete [Theme Documentation](docs/THEMES.md) for detailed information about themes and interactive features.**
+
 ## Performance
 
 **For Large Projects:**

mvn_tree_visualizer-1.5.0/RELEASE.md

@@ -0,0 +1,185 @@
+# Release Procedure
+
+This document describes the automated release process for `mvn-tree-visualizer` using `python-semantic-release`.
+
+## Overview
+
+The project uses automated releases with **python-semantic-release**:
+- **Automatic versioning** based on conventional commit messages
+- **Automatic CHANGELOG.md generation** from commit history
+- **Automatic PyPI publication** when code is pushed to `master`
+- **Automatic GitHub releases** with release notes
+
+### Workflow Branches:
+- `develop` - Active development branch where features are integrated
+- `master` - Protected production branch, triggers automated releases
+- `feature/*` - Individual feature branches
+
+## Conventional Commits
+
+All commits must follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+### Commit Types and Version Impact:
+- `feat:` - New feature → **MINOR** version bump (1.3.0 → 1.4.0)
+- `fix:` - Bug fix → **PATCH** version bump (1.3.0 → 1.3.1)  
+- `perf:` - Performance improvement → **PATCH** version bump
+- `feat!:` or `BREAKING CHANGE:` → **MAJOR** version bump (1.3.0 → 2.0.0)
+- `docs:`, `style:`, `refactor:`, `test:`, `chore:` - No version bump
+
+### Examples:
+```bash
+feat: add theme support with --theme option
+fix: resolve dependency parsing error with special characters  
+feat!: change CLI interface for better usability
+docs: update README with theme examples
+```
+
+## Automated Release Process
+
+### 1. Development Workflow
+
+```bash
+# Create feature branch from develop
+git checkout develop
+git pull origin develop
+git checkout -b feature/add-theme-support
+
+# Make changes and commit using conventional commits
+git add .
+git commit -m "feat: add theme system with dark/light modes"
+git push origin feature/add-theme-support
+```
+
+### 2. Create Pull Request to Develop
+
+Create a pull request from your feature branch to `develop`:
+- Title: Clear description of the feature
+- Description: Details of changes and any breaking changes
+- Ensure all tests pass in CI
+
+### 3. Merge to Develop
+
+Once the PR is reviewed and approved, merge it into `develop`.
+
+### 4. Release to Master
+
+When ready for a release:
+
+```bash
+# Create release PR from develop to master
+git checkout develop
+git pull origin develop
+```
+
+Create a pull request from `develop` to `master`:
+- Title: "Release: Prepare for next version"
+- Description: Summary of changes since last release
+- List any breaking changes
+
+### 5. Automated Release (Master Branch)
+
+When the release PR is merged to `master`, the automation triggers:
+
+1. **python-semantic-release analyzes commits** since the last release
+2. **Determines version bump** based on conventional commit types
+3. **Updates version** in `pyproject.toml`
+4. **Generates CHANGELOG.md** from commit messages
+5. **Creates Git tag** with new version
+6. **Builds package** using `python -m build`
+7. **Publishes to PyPI** automatically
+8. **Creates GitHub release** with generated release notes
+
+## Manual Release (Emergency)
+
+For emergency releases or manual intervention:
+
+```bash
+# Install semantic-release locally
+uv sync --dev
+
+# Preview what will be released (dry-run)
+uv run semantic-release --dry-run
+
+# Force a specific version type
+uv run semantic-release --patch  # or --minor, --major
+
+# Generate changelog only
+uv run semantic-release changelog
+```
+
+## Monitoring Releases
+
+### Check Release Status:
+1. **GitHub Actions**: Monitor the [release workflow](https://github.com/dyka3773/mvn-tree-visualizer/actions)
+2. **PyPI**: Verify new version appears on [PyPI](https://pypi.org/project/mvn-tree-visualizer/)
+3. **GitHub Releases**: Check [GitHub releases page](https://github.com/dyka3773/mvn-tree-visualizer/releases)
+
+### Troubleshooting:
+
+**Failed Release:**
+- Check GitHub Actions logs for specific errors
+- Verify conventional commit format in recent commits
+- Ensure GITHUB_TOKEN has sufficient permissions
+- Check PyPI trusted publishing configuration
+
+**No Version Bump:**
+- Ensure commits follow conventional commit format
+- Check that commits include `feat:` or `fix:` types
+- Verify commits are not filtered out by semantic-release config
+
+## Configuration
+
+The release behavior is configured in `pyproject.toml`:
+
+```toml
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = "python -m build"
+upload_to_pypi = true
+upload_to_release = true
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "style", "refactor", "test"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+```
+
+## Migration from Manual Process
+
+**Previous manual steps no longer needed:**
+- ❌ Manual version updates in `pyproject.toml`
+- ❌ Manual CHANGELOG.md editing
+- ❌ Manual Git tag creation
+- ❌ Manual PyPI uploads
+
+**New automated process:**
+- ✅ Conventional commit messages
+- ✅ Automatic version management
+- ✅ Automatic changelog generation
+- ✅ Automatic PyPI publishing
+- ✅ Automatic GitHub releases
+
+## Emergency Procedures
+
+### Rollback a Release:
+```bash
+# Revert the problematic release commit
+git revert <release-commit-hash>
+
+# Push to master to trigger new patch release
+git push origin master
+```
+
+### Hotfix Process:
+```bash
+# Create hotfix branch from master
+git checkout master
+git checkout -b hotfix/critical-bug-fix
+
+# Make minimal fix
+git commit -m "fix: resolve critical security vulnerability"
+
+# Create PR directly to master (bypass develop for emergencies)
+```
+
+This automated approach ensures consistent, reliable releases while reducing manual effort and human error.