Skip to content

release-validation.md

Latest commit

 

History

History
97 lines (65 loc) · 5.07 KB

release-validation.md

File metadata and controls

97 lines (65 loc) · 5.07 KB

Release Validation

This document defines the heavier pre-release validation flow for MarpToPptx.

Hosted Release Gate

Use the GitHub Actions workflow .github/workflows/release-gate.yml for the automated hosted pre-release gate.

Workflow name: Release Gate

Purpose:

  • run restore, build, tests, and packaging in the selected configuration
  • generate the full sample set, including the remote-assets sample and the opt-in theme fixtures under samples/themes/
  • validate every generated PPTX with the Open XML SDK helper
  • audit a curated set of generated PPTX files with the contrast auditor and upload per-deck reports
  • import every generated PPTX into LibreOffice Impress and export it to PDF
  • upload the generated PPTX, PDF, and package artifacts for manual inspection

This gate is stronger than normal CI because it checks every sample deck and forces a second PPTX consumer to load the generated files.

It also adds a cross-platform rendering-focused gate by failing when the contrast auditor detects text/background pairs that do not meet the repo's WCAG-based thresholds on the curated validation subset.

The current contrast-stable subset is:

  • 01-minimal.pptx
  • 04-content-coverage.pptx
  • 07-presenter-notes.pptx

Other generated decks still ship as release artifacts for manual review, but they are not yet used as hard contrast gates because several of them intentionally exercise theme or directive combinations that are not contrast-stable enough for binary pass/fail enforcement.

This gate is still not equivalent to PowerPoint Desktop compatibility.

Manual PowerPoint Review

PowerPoint Desktop review is a manual release checklist, not an automated GitHub-hosted gate.

Reason:

  • GitHub-hosted runners do not provide a supported PowerPoint Desktop environment for COM-based validation.
  • The most reliable PowerPoint check is still a human opening the generated decks in PowerPoint and reviewing them visually.

Generate Review Artifacts

From the repo root on a Windows machine with PowerPoint installed:

pwsh ./scripts/Generate-SamplePptxSet.ps1 -Configuration Release -OutputDirectory artifacts/manual-review -IncludeThemeSamples -IncludeRemoteSamples -Force

If you want the standard Open XML validation at the same time for a specific deck, run the existing smoke helper:

pwsh ./scripts/Invoke-PptxSmokeTest.ps1 -InputMarkdown samples/01-minimal.md -Configuration Release
pwsh ./scripts/Invoke-PptxSmokeTest.ps1 -InputMarkdown samples/06-remote-assets.md -Configuration Release -AllowRemoteAssets

The single-deck smoke helper runs the contrast auditor by default and writes a sibling *-contrast-audit.txt report next to the generated PPTX.

The aggregate smoke suite uses -ContrastAuditMode Selected by default so CI gets actionable rendering coverage without failing on intentionally contrast-unstable repro decks.

Review Checklist

Open each generated deck from artifacts/manual-review/ in PowerPoint Desktop and confirm:

  • the file opens without a repair dialog, corruption message, or content-loss warning
  • slide count matches the source markdown expectations
  • text layout is readable and does not visibly overflow or overlap in unexpected ways
  • background color and background image behavior match the sample intent
  • headers, footers, and page numbers appear on the expected slides
  • class-variant theme styling appears correctly on 03-theme-css.pptx
  • code blocks, lists, and tables remain editable and visually coherent
  • local media placeholders and embedded media objects appear as expected on 04-content-coverage.pptx
  • remote asset slides render correctly on 06-remote-assets.pptx
  • presenter notes appear on the expected slides in 07-presenter-notes.pptx, and the control slide has no notes

Sample Focus Areas

  • 01-minimal.pptx: baseline slide generation
  • 02-directives.pptx: front matter, carry-forward directives, background image and size behavior, headers, footers, paginate
  • 03-theme-css.pptx: theme parsing, heading hierarchy, class variants, layout-sensitive typography
  • 04-content-coverage.pptx: images, tables, code, MP3, M4A, video
  • 05-compatibility-gaps.pptx: current non-goals, known-approximation behavior, and recently implemented compatibility regression checks
  • 06-remote-assets.pptx: real HTTP(S) image fetches
  • 07-presenter-notes.pptx: explicit presenter notes packaging and slide-to-notes attachment

Theme Fixture Focus Areas

  • 09-community-beam.pptx: academic-style theme fixture with assertive heading and contrast-slide styling
  • 10-community-graph-paper.pptx: local SVG patterned background fixture for theme background fidelity
  • 11-community-wave.pptx: local SVG/art background fixture for bold section-band rendering
  • 12-community-dracula.pptx: dark-theme fixture stressing contrast and code-heavy slide treatment
  • 13-popular-gaia.pptx: bright-theme fixture stressing large-scale typography and clean-surface layout

Current Exclusions

  • Generated-deck-as-template validation is not part of the release gate while issue #66 is open.