Expand migration guide with validation, rollback, and hybrid setup

[andypost]

Summary

Significantly expanded the migration documentation with comprehensive guidance on validation procedures, rollback steps, and a new hybrid installation path for RHEL/Fedora users combining FreeUnit core with Remi PHP modules. Also corrected numerous documentation formatting issues and updated version references.

Key Changes

• Added Migration Plan section with a 5-step pre-migration checklist covering inventory, backup, install path selection, scheduling, and rollback preparation

• New Hybrid Installation Path (migration-remi-hybrid) for RHEL/Fedora users to keep existing Remi PHP modules while swapping only the Unit core to FreeUnit, with detailed procedure and mixing limits

• Comprehensive Validation section with 6 independent checks (daemon startup, socket connectivity, config matching, module loading, end-to-end requests, log cleanliness) to verify successful migration before removing archived packages

• Expanded Rollback Procedure with detailed steps for Docker, source builds, and package-based installations

• Source Build Documentation improvements:

  • Clarified that ./configure is called once per module (not combined --modules= flag)
  • Added systemd service file template
  • Documented that unitctl is a separate binary not installed by the Makefile
  • Updated supported language versions (removed Node.js 24, Go 1.26)

• Docker Documentation updates:

  • Changed docker-compose to docker compose (modern syntax)
  • Updated version output examples to match actual format
  • Clarified that NXT_NAME constant hasn't been renamed, so version string still reads "unit"

• Fixed Documentation Formatting:

  • Corrected RST metadata indentation in header
  • Escaped asterisk in "*BSD" to prevent italic formatting
  • Removed incorrect :ref: cross-references (e.g., :ref:socket`` → plain text)
  • Standardized section underline lengths
  • Updated FAQ with clearer verification instructions

• Removed CI Workflow (docs-build-push.yml) and simplified docs.yml to basic validation-only build

• Updated Contents to include migration guide in main TOC and fixed configuration reference path

Notable Details

• Validation section emphasizes that config matching is "the single most common migration regression"
• Hybrid path includes explicit warning that it's temporary until native FreeUnit PHP RPMs ship
• All version examples updated to 1.35.3 with proper output format
• Added guidance on checking module presence on disk before attempting config validation

https://claude.ai/code/session_01D1xijYKZC3jFYCuk6ZjK4D

[andypost]

Despite the successful resolution of the major problems, a few items still need attention:

1. Truncated File and Missing Newline (New Critical Issue): The migration.rst file ends abruptly midsentence ("Module ABI mismatches (especially for"), lacks a terminating newline, and is missing content that should follow. The file needs to be completed and properly terminated.

2. Sitemap Decision: It hasn't been determined whether the new migration.html page should be indexed in the sitemap. The sitemapexclude.txt file should be updated accordingly.

3. Section Adornment Consistency: While not explicitly spotted in this review, the PR's commit message confirms that it resolved "7 titles, 11 overline warnings" by extending underlines. However, a final visual pass of all headings in the raw file is recommended to ensure consistency.

4. Minor Nitpicks: The commit message mentions several factual corrections were made, but some minor details mentioned in the original review (like Nix alias dates, FreeBSD MOVED dates, etc.) should be spot-checked to ensure they were all caught.

The next step should be to fix the truncated file issue, make a final pass on the remaining nits, and then re-request a build to ensure Sphinx runs with zero warnings. Let me know if you'd like me to elaborate on any of these points.