v0.2.4 - Fix race condition on GitHub authors (#177)

🌟 Summary

v0.2.4 makes the MkDocs Ultralytics plugin more reliable and stable by fixing a GitHub author resolution race condition and modernizing the CI workflow dependencies. 🧱✨

---

📊 Key Changes

• 🧵 Race-condition fix for GitHub authors (PR #177 by @glenn-jocher)

  • GitHub author info is now resolved once in the main process via resolve_all_authors() before any multiprocessing begins.
  • Worker processes now only read precomputed author data from git_data—they no longer write to the author cache.
  • The previous global, thread-locked cache has been replaced with a clear load / resolve / save flow using:
    • load_author_cache()
    • resolve_github_user() / resolve_all_authors()
    • save_author_cache()
  • processor.get_git_info() and process_html() are simplified: they no longer accept default_author and repo-specific author parameters, and now just read pre-resolved authors.

• 💾 Safer and more robust author caching logic

  • Author cache is stored in a single YAML file: mkdocs_github_authors.yaml.
  • Cache is now updated once per run in the main process, avoiding concurrent writes and file corruption.
  • A new helper get_default_avatar() lazily fetches and caches the GitHub default avatar URL, with timeouts and fallbacks for network errors.

• 🌐 More resilient GitHub API calls

  • All GitHub-related HTTP calls now use a fixed timeout to prevent hangs.
  • Graceful fallbacks:
    • If avatar resolution fails, the plugin falls back to a safe default avatar URL.
    • If GitHub user lookup fails, authors are still rendered with sensible defaults (e.g., repo URL instead of profile URL).

• 🧹 Codebase cleanup and simplification

  • Utility functions simplified and tightened:
    • get_youtube_video_ids() signature and docstring streamlined.
  • get_git_info() now clearly:
    • Uses precomputed creation_date and last_modified_date.
    • Reads authors directly from the already-resolved git_data.

• ⚙️ CI workflow updates for GitHub Actions

  • actions/checkout upgraded from v5 → v6.
  • actions/upload-artifact upgraded from v5 → v6.
  • actions/download-artifact upgraded from v6 → v7.
  • These updates move the workflows to Node.js 24–based actions, keeping the release pipeline modern and compatible with the latest GitHub infrastructure.

---

🎯 Purpose & Impact

• 🚫 Eliminates intermittent build failures

  • The previous design allowed multiple parallel workers to write to mkdocs_github_authors.yaml at the same time, causing race conditions and occasional cache corruption.
  • By resolving authors once in the main process and making workers read-only, v0.2.4 removes this entire class of errors.

• ✅ More reliable documentation builds

  • MkDocs sites using this plugin (especially with multiprocessing enabled) will now build more consistently and predictably, with fewer hard-to-reproduce failures.
  • Teams running CI builds or automated doc deployments benefit from higher stability and less flakiness.

• 🧠 Simpler mental model for contributors

  • Author resolution now follows a straightforward pipeline:
    1. Build git map.
    2. Pre-resolve all authors in the main process.
    3. Save a single cache file.
    4. Let workers consume read-only git_data.
  • This makes the code easier to understand, maintain, and extend for future features.

• 🌍 Better behavior in real-world environments

  • Network errors, slow GitHub responses, or avatar resolution issues are now handled gracefully with timeouts and fallbacks, avoiding long hangs or crashes during docs builds.

• 🔒 Future-proof CI & tooling

  • Updating to the latest actions/* versions means:
    • Continued support for GitHub-hosted runners and modern Node.js versions.
    • Fewer surprises as older action versions are deprecated.
  • This keeps the publish pipeline for the plugin secure, current, and maintainable.

Overall, v0.2.4 is a stability and robustness release: no user-facing configuration changes are required, but your MkDocs builds using the Ultralytics plugin should now be more dependable and less error-prone. 🚀📚

What's Changed

• Bump actions/checkout from 5 to 6 in /.github/workflows by @dependabot[bot] in #174
• Bump actions/download-artifact from 6 to 7 in /.github/workflows by @dependabot[bot] in #176
• Bump actions/upload-artifact from 5 to 6 in /.github/workflows by @dependabot[bot] in #175
• Fix race condition on GitHub authors by @glenn-jocher in #177

Full Changelog: v0.2.3...v0.2.4