Roadmap — SOGo User Guide (5 & 6)

Status: ✅ Published — 27 SOGo 5 docs, 36 visual assets (WebP + PNG), Docusaurus versioning for SOGo 5 + SOGo 6, CI/CD with self-hosted runners, 99.34% test coverage, SEO/GEO targeting, task-first capture flow with HTML5 video

Demo Sites:

• SOGo 5: https://demo.sogo.nu/
• SOGo 6: https://demov6.sogo.nu/

Build Status: CI pipeline using self-hosted runner on legions (192.168.42.42). Builds take ~4-5 min (cached) / ~10 min (cold).

Staging: Deferred — own preview deployment system replacing Netlify (see Sprint 13).

---

Completed ✅

Sprint 1: Spec Foundation (OpenSpec)

• Initialize openspec/specs/ directory structure
• Write specs for core capture pipeline domains: auth-login, calendar, mail, contacts, preferences
• Each spec includes: Purpose, Requirements (RFC 2119), Scenarios (Given/When/Then)
• Configure openspec/config.yaml with project settings

Sprint 2: CI/CD Pipeline

• Create .github/workflows/ci.yml — run on push/PR to main
• Lint: ruff on capture/ Python code
• Test: pytest with 99.34% coverage on capture/tests/ + accessibility/tests/
• Build: Docusaurus build for both en + de locales
• Deploy: GitHub Pages deployment on main push
• Self-hosted runner on legions (192.168.42.42) with labels linux, legions
• Runner service: legions-docmaker-runner

Sprint 3: Asset Optimization

• Create capture/optimize.py — batch image optimizer
• WebP optimization: color palette reduction, frame skip, metadata stripping
• PNG optimization: pngquant, metadata stripping
• 36 tests for optimize.py
• 54% size reduction achieved (2.1MB → 976KB per version)

Sprint 4: Capture Reliability

• Add validation step: blank detection (>90% white)
• Structured logging to capture failures
• Create capture/capture_report.py — artifact quality report
• Re-capture logic with retry

Sprint 5: Parallel Execution

• Implement parallel workflow execution
• Configurable workers via semaphore
• Sequential ordering for dependencies (login → workflows)
• 12 tests for parallel_runner.py

Sprint 6: Accessibility Gates

• Integrate accessibility/validate.py as CI step
• Add auto-fix mode for fixable issues (heading hierarchy, table headers)
• 30 tests for accessibility/validate.py
• WCAG 2.1 Level A checklist generation

Sprint 7: Video/MP4 Pipeline

• Create scripts/convert_to_mp4.py — WebP → MP4 (H.264) + WebM (VP9)
• MP4: libx264, CRF 23, yuv420p, fast start
• WebM: libvpx-vp9, CRF 30
• Thumbnail/poster generation

Sprint 8: User Journeys & SEO

• Task-first capture flow with 4-beat narrative (Context, Challenge, Solution, Result)
• Human-like typing (120ms delay on form fields)
• SEO components: Open Graph, Twitter Cards, Schema.org (SoftwareApplication, HowTo, TechArticle)
• GEO targeting: geo.region="DE", geo.placename="Berlin", ICBM
• Path restructuring: sogo5/sogo6 instead of /5//6/
• Sidebar reorganized into 7 categories with emoji icons

Sprint 2b: CI Reliability

• Docusaurus build time optimization (4-5 min cached, ~10 min cold — down from 30+)
• Python lint/test stability (PEP 668 compatibility with --break-system-packages)
• Node.js version compatibility (Node 20 vs Node 24 on Arch rolling)
• Branch protection rules: separate CI status checks from deploy gate
• Runner resource contention: load balance between CI/Deploy/Preview workflows

Sprint 9: Performance Benchmarks

• Add Lighthouse CI to .github/workflows/ci.yml
• Add bundle size tracking
• Add capture timing metrics to capture_report.py
• Set up performance budgets (LCP <2.5s, total bundle <500KB gzip)
• Create performance dashboard page at site/docs/performance.md

Sprint 12: Spec-to-Docs Pipeline

• Auto-generate documentation pages from OpenSpec specs
• Tutorial structure from spec scenarios
• Asset embedding from capture metadata
• Docusaurus sidebar auto-generation
• scripts/generate_docs_from_specs.py (593 lines) shipped in commit 25bed47

Sprint 14: Repo Hygiene

• Untrack .github-pages-trace debug artifact
• Remove empty docs/ directory
• Sync ROADMAP with actual state
• Add CI guard for coverage threshold regression (>0.5% drop fails PR)

Sprint 11: SOGo Change Detection

• Create capture/detect_changes.py — perceptual-hash UI diff
• ImageHash-based screenshot comparison (pHash, 64-bit)
• Hamming distance threshold (default: 10 bits)
• Auto-baseline-update on drift detection
• Nightly CI workflow (.github/workflows/change-detection.yml) posts GitHub Issue on drift
• capture/run_captures.py integrates drift check per workflow
• DOM structure comparison (deferred — pHash covers most cases)

Infrastructure

• Self-hosted runner on legions (192.168.42.42)
• Runner name: legions-docmaker-runner
• Labels: linux, legions
• SSH config updated
• Test coverage: 99.34% (192/192 tests passing)
• coverage.xml artifact upload in CI

---

In Progress 🔵

None — all tracked sprints are either completed or planned.

---

Completed ✅

All sprints completed. DOM structure comparison in Sprint 11 deferred (pHash covers most cases).

Sprint 10: Content Expansion

• Recapture critical workflows with task-first approach (converted 3 existing WebM to MP4)
• Convert task-first WebP captures to MP4 (3 videos optimized, 6-11% smaller)
• Add VideoFallback component and WebVTT captions (component created + 1 tutorial updated)
• Add PageSEO to key tutorial pages (compose, add contact, reply/forward, edit/delete)
• Full German translation of /sogo5/de/

Sprint 13: PR Preview Deployments

• Rewrite preview-deploy.yml — build with dynamic baseUrl, deploy to gh-pages/preview/pr-<N>/
• Preview URL commented on PRs (upserts existing comment instead of spamming)
• Teardown workflow (preview-cleanup.yml) — deletes preview directory on PR close
• Update workflow README with preview URL info
• Decide: gh-pages /preview/ subdirectory (chosen over staging branch)

---

Accessibility

This documentation site supports keyboard navigation, screen readers, and high-contrast mode.

Keyboard Navigation

Shortcut:	Action:
Tab	Navigate between links and interactive elements
Enter / Space	Activate links and buttons
Ctrl + F	Search within the current page

Screen Reader & High Contrast

• All tables use proper header markers (| Header | format) for screen reader column navigation
• Status icons include text alternatives (e.g., "✅ Completed" not just an emoji)
• High-contrast mode is supported via system prefers-contrast: more media queries
• Color is never the sole means of conveying information

Known Issues

Issue:	Status:	Notes:
Docusaurus build takes 30+ min on legions	🔵	Node 24 vs Node 20, npm cache cold
Python PEP 668 blocks pip	✅ Fixed	--break-system-packages added
@docusaurus/remark-plugin-content-docs infinite loop	✅ Fixed	Plugin removed, using manual PageSEO imports
GitHub API intermittent connectivity	⚠️	api.github.com connection issues
Deploy workflow hangs on German locale build	🔵	Suspected Node.js version mismatch

---

Legend

Icon:	Meaning:
✅	Completed
🔵	In Progress
🟡	Planned
❌	Blocked
⚠️	Degraded

---

Last Updated: 2026-06-29 Next Sprint: None — roadmap complete. Future work tracked via GitHub Issues.

---

Appendix: Key Metrics

Metric:	Value:
Test coverage	99.34% (192/192 passing)
CI runner	Self-hosted on legions (192.168.42.42)
Runner labels	linux, legions
Runner version	2.335.1
SEO geo tags	geo.region=DE, geo.placename=Berlin, ICBM
Asset size reduction	54% (2.1MB → 976KB)
Documentation pages	27 SOGo 5 + 30 SOGo 6 docs
Path structure	/sogo5/, /sogo6/