mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +00:00

Files

Chuck ef579dd191 docs: fix broken file references found by path-existence crosscheck

Ran a doc-vs-filesystem crosscheck: extracted every backtick-quoted
path with a file extension or known directory prefix from docs/*.md
and verified each exists. After filtering false positives
(placeholder paths, config keys mistaken for paths, paths inside
docs that already have historical-status banners), found 4 real
broken references — 3 fixed in docs, 1 fixed by creating the missing
file:

docs/HOW_TO_RUN_TESTS.md:339
- Claimed ".github/workflows/tests.yml" exists and runs pytest on
  multiple Python versions in CI. There is no such workflow.
  The only GitHub Actions file is security-audit.yml (bandit + semgrep).
- Pytest runs locally but is NOT gated on PRs.
- Replaced the fictional CI section with the actual state and a
  note explaining how someone could contribute a real test workflow.

docs/MIGRATION_GUIDE.md:92
- Referenced scripts/fix_perms/README.md "(if exists)" — the
  hedge betrays that the writer wasn't sure. The README didn't
  exist. The 6 scripts in scripts/fix_perms/ were never documented.
- Created the missing scripts/fix_perms/README.md from scratch
  with one-line descriptions of all 6 scripts (fix_assets,
  fix_cache, fix_plugin, fix_web, fix_nhl_cache, safe_plugin_rm)
  + when-to-use-each guidance + usage examples.
- Updated MIGRATION_GUIDE link to drop the "(if exists)" hedge
  since the file now exists.

docs/FONT_MANAGER.md:376
- "See test/font_manager_example.py for a complete working example"
  — that file does not exist. Verified by listing test/ directory.
- Replaced with a pointer to src/font_manager.py itself and the
  existing scoreboard base classes in src/base_classes/ that
  actually use the font manager API in production.

Path-existence check methodology:
- Walked docs/ recursively, regex-extracted backtick-quoted paths
  matching either /\.(py|sh|json|yml|yaml|md|txt|service|html|js|css|ttf|bdf|png)/
  or paths starting with known directory prefixes (scripts/, src/,
  config/, web_interface/, systemd/, assets/, docs/, test/, etc.)
- Filtered out URLs, absolute paths (placeholders), and paths
  without slashes (likely not relative refs).
- Checked existence relative to project root.
- Out of 80 unique relative paths in docs/, 32 didn't exist on
  disk. Most were false positives (configkeys mistaken for paths,
  example placeholders like 'assets/myfont.ttf', historical
  references inside docs that already have status banners). The 4
  above were genuine broken refs.

This pattern is reusable for future iterations and worth wiring
into CI (link checker like lychee, scoped to fenced code paths
rather than just markdown links, would catch the same class).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-07 16:22:48 -04:00

3.0 KiB

Raw Blame History

Migration Guide

This guide helps you migrate from older versions of LEDMatrix to the latest version.

Breaking Changes

Script Path Reorganization

Scripts have been reorganized into subdirectories for better organization. If you have automation, cron jobs, or custom tooling that references old script paths, you must update them.

Installation Scripts

All installation scripts have been moved from the project root to scripts/install/:

Old Path	New Path
`install_service.sh`	`scripts/install/install_service.sh`
`install_web_service.sh`	`scripts/install/install_web_service.sh`
`install_wifi_monitor.sh`	`scripts/install/install_wifi_monitor.sh`
`setup_cache.sh`	`scripts/install/setup_cache.sh`
`configure_web_sudo.sh`	`scripts/install/configure_web_sudo.sh`
`migrate_config.sh`	`scripts/install/migrate_config.sh`

Permission Fix Scripts

All permission fix scripts have been moved to scripts/fix_perms/:

Old Path	New Path
`fix_assets_permissions.sh`	`scripts/fix_perms/fix_assets_permissions.sh`
`fix_cache_permissions.sh`	`scripts/fix_perms/fix_cache_permissions.sh`
`fix_plugin_permissions.sh`	`scripts/fix_perms/fix_plugin_permissions.sh`
`fix_web_permissions.sh`	`scripts/fix_perms/fix_web_permissions.sh`

Action Required

Update cron jobs: If you have any cron jobs that call these scripts, update the paths.
Update automation scripts: Any custom scripts or automation that references the old paths must be updated.
Update documentation: Update any internal documentation or runbooks that reference these scripts.

Example Updates

Before:

# Old cron job or script
0 2 * * * /path/to/LEDMatrix/fix_cache_permissions.sh
sudo ./install_service.sh

After:

# Updated paths
0 2 * * * /path/to/LEDMatrix/scripts/fix_perms/fix_cache_permissions.sh
sudo ./scripts/install/install_service.sh

Verification

After updating your scripts, verify they still work:

# Test installation scripts (if needed)
ls scripts/install/*.sh
sudo ./scripts/install/install_service.sh --help

# Test permission scripts
ls scripts/fix_perms/*.sh
sudo ./scripts/fix_perms/fix_cache_permissions.sh

Other Changes

Configuration File Location

No changes to configuration file locations. The configuration system remains backward compatible.

Plugin System

The plugin system has been enhanced but remains backward compatible with existing plugins.

Getting Help

If you encounter issues during migration:

Check the README.md for current installation and usage instructions
Review script README files:
- scripts/install/README.md - Installation scripts documentation
- scripts/fix_perms/README.md - Permission scripts documentation
Check system logs: journalctl -u ledmatrix -f or journalctl -u ledmatrix-web -f
Review the troubleshooting section in the main README

3.0 KiB Raw Blame History