Development

This section is for contributors. See Architecture for module internals and Theme Palette Sources for palette attribution.

Branch Names

Use short-lived, descriptive branches. Branch names must begin with one of these prefixes:

• feature/
• fix/
• hotfix/
• chore/
• docs/
• refactor/
• test/
• ci/

For example: docs/branch-name-policy.

PowerShell Checks

Test-ModuleManifest ./src/gly.psd1
npm test
npm run test:coverage

npm test creates JUnit XML, CTRF JSON, and a self-contained HTML report in artifacts/tests/local. The coverage command also creates a Cobertura report. CI publishes each test and coverage format as a separate artifact, including HTML and Markdown coverage reports, plus the ZIP and NuGet module packages. It rejects line-coverage regressions larger than one percentage point from the latest successful master run.

Use npm test -- --TestType Unit or npm test -- --TestType Snapshots to run one test type. CI runs both types in parallel on each supported operating system and stores their reports separately.

The runner exports JUnit after Pester finishes. XML-invalid control characters in failure messages and stack traces are written as readable escapes such as \u001b, so failed ANSI assertions still produce JUnit, CTRF, and HTML reports. The runner reports a failed test run after generating the reports. Cross-platform hidden-file fixtures use a leading dot in the file name and explicitly set the Windows hidden attribute.

After the test jobs finish, a dedicated CI job combines their CTRF artifacts into the GitHub test summary. Coverage and benchmark summaries are published by a separate job.

The Pester suite includes committed snapshots in tests/snapshots. They cover the exported command surface, built-in themes and glyph sets, previews, session configuration, display names, and renderers. Literal output snapshots also cover Get-Item, Get-ChildItem, Show-Gly, Show-GlyTree, and Show-GlyGrid with a fixed fixture and output width. Separate Windows, Linux, and macOS snapshots preserve platform-specific spacing, file modes, and line endings. CI compares the output with these snapshots on all three platforms. When an intentional behavior change requires new snapshots, regenerate them on each platform with PowerShell 7 and review the diff:

$env:GLY_UPDATE_SNAPSHOTS = '1'
Invoke-Pester ./tests/Snapshots.Tests.ps1
Remove-Item Env:GLY_UPDATE_SNAPSHOTS
npm test

The Refresh snapshots GitHub Actions workflow can be run manually from the Actions tab. It generates snapshots on Linux, Windows, and macOS, then opens or updates a pull request to master when the committed snapshots change and starts CI for that branch. Review the diff before merging.

Performance Benchmarks

npm run bench
npm run bench:startup
npm run bench:rendering

The combined command runs the independent startup and rendering suites concurrently while each suite keeps its own timed measurements sequential. The startup benchmark uses isolated PowerShell processes. The rendering benchmark covers display-name, standard-table, and renderer paths against generated file-system data. Each rendering scenario runs with the PSStyle, Ansi, and PlainText style backends, and reports the backend in the StyleRenderer column for direct comparison.

Pass -- --OutputPath ./artifacts/benchmarks/local to the combined command to write startup.json and rendering.json to that directory.

CI runs both benchmark suites sequentially on ubuntu-26.04, publishes their median timings in the workflow summary, and stores the JSON results as the benchmark-results-ubuntu-26.04 artifact. Each run compares matching scenarios with the committed startup.json and rendering.json files in benchmarks/baselines/ubuntu-26.04. A scenario fails the regression gate when its median time is more than 20% slower. If no baseline exists for the runner image or a scenario, CI reports Baseline unavailable and skips that comparison; ordinary CI runs never update the baselines.

Run the Refresh benchmark baselines GitHub Actions workflow manually from the Actions tab to establish or intentionally update the baselines. It runs the same startup and rendering suites sequentially on ubuntu-26.04, uploads the generated JSON files, then opens or updates a pull request to master and starts CI for that branch. Review the timing changes before merging. The new baselines take effect in subsequent runs after the pull request is merged. Keep baselines in a separate directory for each runner image when changing runners.

Documentation Site

npm ci
npm run docs:dev
npm run docs:build
npm run docs:preview

The VitePress source root is docs.

Documentation builds in CI and the publishing workflow validate that package.json's version matches ModuleVersion in src/gly.psd1. A mismatch fails the job before building the documentation site. Keep both versions in sync when preparing a release.

Repository Maintenance

GitHub repository metadata documents the contribution, support, and security processes:

• Contributing guidelines
• Code of Conduct
• Security policy
• Support guidance

Issue forms and the pull request template live in .github. Dependabot checks npm dependencies and GitHub Actions weekly. Repository administrators should keep private vulnerability reporting, Dependabot security updates, secret scanning, and push protection enabled.