Skip to content

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

@MariusStorhaug

Description

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

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:

Progress Tracking

Wave 1 Progress (12 modules)

Module PR Status Notes
Base64 - Not Started
Json - Not Started
Yaml - Not Started
Toml - Not Started
Guid - Not Started
Retry - Not Started
Object - Not Started
Hashtable - Not Started
Path - Not Started
TimeSpan - Not Started
Uri - Not Started
DateTime - Not Started

Wave 2 Progress (22 modules)

Module PR Status Notes
Net - Not Started
IPv4 - Not Started
IPv6 - Not Started
Dns - Not Started
Tls - Not Started
GZip - Not Started
MemoryMappedFile - Not Started
Sodium - Not Started
Jwt - Not Started
GraphQL - Not Started
Markdown - Not Started
PowerShellDataFile - Not Started
PSCredential - Not Started
PSCustomObject - Not Started
PSSemVer - Not Started
CasingStyle - Not Started
DynamicParams - Not Started
Ast - Not Started
Hcl - Not Started
Lua - Not Started
PowerShellGallery - Not Started
Utilities - Not Started

Wave 3 Progress (15 modules)

Module PR Status Notes
OpenAI - Not Started
Claude - Not Started
Anthropic - Not Started
DeepSeek - Not Started
Gemini - Not Started
GitHub - Not Started
Discord - Not Started
Twitch - Not Started
LinkedIn - Not Started
Bluesky - Not Started
Confluence - Not Started
AzureDevOps - Not Started
CurseForge - Not Started
Domeneshop - Not Started
PublicIP - Not Started

Wave 4 Progress (10 modules)

Module PR Status Notes
Admin - Not Started
Context - Not Started
Context7 - Not Started
DistTestModule - Not Started
ElvUI - Not Started
Fonts - Not Started
GoogleFonts - Not Started
NerdFonts - Not Started
Telemetry - Not Started
WoW - Not Started

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)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions