Skip to content

Cronjob Documentation System

This directory contains auto-generated documentation for all cronjobs defined in system-crontab.md.

Overview

Cronjobs are production-critical workflows that run silently in the background. This documentation system ensures:

  • 🔍 Visibility: Every cronjob has structured documentation
  • 📊 Traceability: Links from cron schedules to Symfony Command classes
  • ⚠️ Risk Assessment: Identification of critical workflows (sales, payments, stock)
  • 🔄 Freshness: Automated checks for documentation completeness and staleness
  • 🚨 CI Enforcement: Automated validation that fails on missing or outdated docs

Statistics

  • Total Entries

    164 active cron entries parsed from system crontab

  • Unique Commands

    115 unique Symfony console commands identified

  • Code Linkage

    95/115 (82%) commands linked to source files

  • High Risk

    46 critical + 40 high risk commands

Browse by Risk Level

Critical Risk (46 commands)

Commands involving sales, payments, refunds, or stock mutations:

High Risk (40 commands)

Commands with significant business impact:

Medium Risk (8 commands)

Supporting commands: logs, statistics, alerts, notifications

Unknown Risk (21 commands)

Commands needing risk assessment through code inspection

Browse Alphabetically

  • A-C - Commands starting with A through C
  • D-M - Commands starting with D through M
  • N-Z - Commands starting with N through Z

Documentation Format

Each cronjob documentation file follows this structure:

---
title: "command:name"
type: cronjob
source: system-crontab
status: active | undocumented
last_verified: YYYY-MM-DD
schedule:
  - "*/10 * * * *"
command:
  - "full:command --with-options"
risk_level: critical | high | medium | unknown
command_class: "src/Path/To/CommandClass.php"
---

# Command Name

## Overview
...

Risk Level Definitions

Level Description Business Impact Examples
🔴 Critical Sales, payments, refunds, stock mutations Immediate financial/inventory impact menzzo:v2:sales:payment
🟡 High Products, sync, orders, imports Significant operational impact menzzo:v2:products
🟢 Medium Logs, stats, alerts, notifications Supporting functions menzzo:statistic
⚪ Unknown Needs assessment Not yet determined Various

Usage

Regenerate Documentation

python3 tools/cronjob_doc_generator.py

This will:

  1. Parse docs/system-crontab.md for all active cron entries
  2. Extract unique Symfony console commands
  3. Generate documentation files in docs/cronjobs/
  4. Attempt to locate corresponding Command class files
  5. Generate docs/meta/documentation-progress.md with coverage statistics

When to Regenerate

Run the generator whenever:

  • ✅ Cron entries are added, removed, or modified in system-crontab.md
  • ✅ Command schedules change
  • ✅ New Command classes are created
  • ✅ Command classes are moved or renamed
  • ✅ You want to refresh coverage statistics

Update System Crontab

# 1. Update crontab
crontab -e

# 2. Document changes
php bin/console logidav:cron:document

# 3. Regenerate docs
python3 tools/cronjob_doc_generator.py

# 4. Commit
git add docs/ && git commit -m "docs: update cronjobs"

CI Enforcement

The GitHub Actions workflow validates documentation on every commit:

  • ✅ All cronjobs have corresponding documentation files
  • ✅ docs/meta/documentation-progress.md exists and is parseable
  • ⚠️ Warns about commands without located class files
  • ⚠️ Warns about commands with unknown risk levels
  • ⚠️ Identifies potentially stale documentation (>90 days old)
  • 📊 Reports coverage statistics

Priority Tasks

Based on the progress report:

🔴 Critical Priority

  1. 46 commands mutating sales, payments, refunds, or stock - REQUIRES IMMEDIATE DOCUMENTATION
  2. 20 commands with no matching Command class or unable to locate

🟡 High Priority

  1. 40 high-risk commands with significant business impact
  2. Add @doc.* annotations to all 95 located Command classes
  3. Document business intent and side effects for all commands

⚪ Unknown Risk

  1. 21 commands need risk assessment through code inspection

Key Principles

  1. Crontab is Source of Truth: system-crontab.md is the authoritative definition
  2. Never Silent: Cronjobs run in background but must be documented
  3. Operational Debt: Undocumented cronjobs are technical debt
  4. Regenerate, Don't Edit: Always regenerate base docs from source
  5. Code Linkage: Documentation must trace to actual Command classes
  6. Risk First: Prioritize documenting critical workflows

Commands Not in This System

This system tracks cronjobs only. It does NOT document:

  • API endpoints
  • Web workflows
  • Manual console commands
  • Event listeners
  • Message queue consumers

These will be addressed in separate documentation initiatives.