Process: Migrate Module Repos to Zensical Framework (Phased Rollout) #337

Overview

This issue tracks the process and progress for migrating PSModule module repositories to use the new Zensical-based Process-PSModule framework. This is a coordinated rollout that runs in parallel with implementation issue #336.

The goal is to transition all 59 module repositories from the legacy MkDocs/Material build to the new Zensical framework in a staged, low-risk manner.

Related Issues

• Implementation: Implement: Migrate Process-PSModule Framework to Zensical (Minor Bump) #336 – Framework migration (Process-PSModule + actions)
• Specification: Specification: Migrate Documentation Pipeline to Zensical with Capability Parity + Code Copy Button #335 – Zensical design and requirements
• Evaluation: Migrate documentation generator from MkDocs to Zensical #255 – Initial Zensical evaluation (closed)

Rollout Strategy

Wave 1: Foundational/Core Modules (Early Adopters)

Well-maintained core modules; good validation canaries

• Base64
• Json
• Yaml
• Toml
• Guid
• Retry
• Object
• Hashtable
• Path
• TimeSpan
• Uri
• DateTime

Process:

• Create feature branch docs/migrate-to-zensical in target repo
• Copy PSModule-standard zensical.toml template from Process-PSModule
• Test local build with zensical build
• Open PR with migration notes
• Validate CI passes (Build-Site workflow with new Process-PSModule version)
• Merge and tag a new version

Wave 2: Utility & Infrastructure Modules

Network, system, and general utilities

• Net
• IPv4
• IPv6
• Dns
• Tls
• GZip
• MemoryMappedFile
• Sodium
• Jwt
• GraphQL
• Markdown
• PowerShellDataFile
• PSCredential
• PSCustomObject
• PSSemVer
• CasingStyle
• DynamicParams
• Ast
• Hcl
• Lua
• PowerShellGallery
• Utilities

Process:

• Batch create PRs to add zensical.toml
• Validate CI passes for each
• Merge in sequence (or batch if no conflicts)
• Tag version updates

Wave 3: AI/Cloud/API Modules

Integrations with external services and AI platforms

• OpenAI
• Claude
• Anthropic
• DeepSeek
• Gemini
• GitHub
• Discord
• Twitch
• LinkedIn
• Bluesky
• Confluence
• AzureDevOps
• CurseForge
• Domeneshop
• PublicIP

Process:

• Review existing mkdocs.yml for custom features
• Create zensical.toml if needed, or use template
• Open PR with detailed migration notes
• Extra validation before merge

Wave 4: Domain-Specific & Specialized Modules

Niche domains, reference implementations, fonts

• Admin
• Context
• Context7
• DistTestModule
• ElvUI
• Fonts
• GoogleFonts
• NerdFonts
• Telemetry
• WoW

Process:

• Migrate with Wave 3 process
• Extra scrutiny for reference/test modules

Prerequisites for Rollout

Before rollout begins:

• Issue Implement: Migrate Process-PSModule Framework to Zensical (Minor Bump) #336 (implementation) reaches "Phase 2: Update Build-Site Workflow" completion
• Process-PSModule framework is tagged with new version that uses Zensical
• Migration guide is published and available to module maintainers
• Test fixtures in Process-PSModule build successfully with Zensical

Progress Tracking

Wave 1 Progress (12 modules)

Wave 2 Progress (22 modules)

Wave 3 Progress (15 modules)

Wave 4 Progress (10 modules)

Communication & Documentation

• Migration guide published (link to docs or wiki)
• Slack/team notification sent with rollout timeline
• FAQ created for common questions
• Troubleshooting guide for Zensical issues

Success Criteria

• All Wave 1 modules migrated and verified
• All Wave 2 modules migrated and verified
• All Wave 3 modules migrated and verified
• All Wave 4 modules migrated and verified
• No regressions in docs build for any module
• Code copy button is functional in all generated docs
• Team confirms migration complete and no follow-up work needed

Notes

• Module repositories can adopt the new framework on their own schedule; backward compatibility is maintained via Zensical's native mkdocs.yml support
• If any repo cannot migrate due to unsupported plugins, create a follow-up issue and track the blocker
• Rollout can pause between waves if issues are discovered; resumption is coordinated in comments below

Next Steps

1. Implementation issue Implement: Migrate Process-PSModule Framework to Zensical (Minor Bump) #336 completes framework migration
2. Open PRs for Wave 1 modules (coordinate with team)
3. Validate Wave 1 builds successfully
4. Proceed to Wave 2
5. Proceed to Wave 3
6. Proceed to Wave 4 with extra scrutiny
7. Close this issue when all modules are migrated (or document exceptions)