Skip to main 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

Directory Structure​

docs/
├── system-crontab.md          # Source of truth for all cronjobs
├── cronjobs/                  # Auto-generated documentation per command
│   ├── menzzo-v2-sales.md
│   ├── menzzo-v2-products.md
│   └── ...
└── meta/
    └── documentation-progress.md  # Coverage report and TODO tracking

Documentation Format​

Each cronjob documentation file follows this structure:

---
title: "command:name"
type: cronjob
source: system-crontab
status: active | undocumented | needs-regeneration
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"
regeneration:
  trigger: "Cron definition or command code changed"
  instruction: "Re-run documentation agent starting from system-crontab.md"
---

# Command Name

## Overview
...

Risk Levels​

  • 🔴 CRITICAL: Commands involving sales, payments, refunds, or stock mutations
  • 🟡 HIGH: Commands with significant business impact (products, sync, orders)
  • 🟢 MEDIUM: Supporting commands (logs, stats, alerts, notifications)
  • ⚪ UNKNOWN: Risk needs assessment through code inspection

Generating Documentation​

Initial Generation​

To generate all cronjob documentation from scratch:

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

Regeneration Policy​

NEVER manually update generated documentation without regenerating.

If a cronjob changes:

  1. Update system-crontab.md if the cron schedule changed
  2. Re-run python3 tools/cronjob_doc_generator.py
  3. Manually enhance the generated docs with business intent
  4. Update last_verified date

CI Enforcement​

Documentation updates should be validated locally and in Jenkins when relevant files change.

What It Checks​

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

CI Failures​

The CI will fail if:

  • Documentation files are missing for cronjobs
  • system-crontab.md or documentation-progress.md is missing
  • Documentation structure is malformed

The CI will pass with warnings if:

  • Command classes couldn't be located (needs manual investigation)
  • Risk levels are marked as "unknown"
  • Documentation is marked as "undocumented"

Documentation Workflow​

1. Initial Bootstrap (DONE)​

  • Parse system-crontab.md
  • Generate skeleton documentation for all cronjobs
  • Create progress tracking
  • Set up CI enforcement

2. Code Traceability (IN PROGRESS)​

For each cronjob:

  1. Locate Command Class

    • Already auto-detected for 95/115 commands
    • Remaining 20 need manual investigation

  2. Add @doc. Annotations* (TODO)

    • Add structured documentation tags to Command classes
    • Example: 
      /**
       * @doc.intent: Syncs sales from Magento 2 to LogiDAV ERP
       * @doc.side_effects: Decrements stock, sends customer emails
       * @doc.risk: critical - modifies sales and stock data
       */

  3. Enhance Documentation (TODO)

    • Fill in business purpose and workflow
    • Document side effects and dependencies
    • Add error handling procedures

3. Maintenance (ONGOING)​

  • Run generator after crontab changes
  • Keep last_verified dates current
  • Monitor CI warnings
  • Address high-risk undocumented commands first

Priority Tasks​

Based on documentation-progress.md:

🔴 Critical Priority (46 commands)​

These commands involve sales, payments, refunds, or stock and require immediate attention:

  • menzzo:v2:sales
  • menzzo:v2:sales:payment
  • menzzo:sale:shipping:dropship
  • menzzo:refund:check
  • ... (see full list in progress doc)

🟡 High Priority (40 commands)​

These commands have significant business impact:

  • menzzo:v2:products
  • menzzo:sync:shipping-rates
  • menzzo:product:stat
  • ... (see full list in progress doc)

⚪ Unknown Risk (21 commands)​

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

Troubleshooting​

Command class not found​

If a Command class can't be located:

  1. Search manually: find src/ -name "*Command.php" | xargs grep "setName('command:name')"
  2. Check if it's an external script (not Symfony)
  3. Update the finder logic in tools/cronjob_doc_generator.py if needed

Documentation out of sync​

If documentation doesn't match system-crontab.md:

# Regenerate everything
python3 tools/cronjob_doc_generator.py

# Check what changed
git diff docs/cronjobs/

CI fails on PR​

If CI fails:

  1. Check the error message in Jenkins
  2. Regenerate docs locally with python3 tools/cronjob_doc_generator.py
  3. Regenerate docs if needed
  4. Commit and push the updates

Questions?​

This documentation system was created as part of a cronjob-first documentation initiative. It treats cronjobs as production-critical workflows that deserve first-class documentation and reliable validation.

For issues or improvements, discuss with the team or update the generator script.