Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
234 lines (175 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

234 lines (175 loc) · 10.7 KB

Contributing

Thank you for contributing to compare-vi-cli-action!

Prerequisites

Baseline repo contribution does not require the full LabVIEW runtime stack. Many docs, policy, Node, and workflow changes can be developed and reviewed on hosted Linux/macOS or a regular local checkout.

Full compare-path and release-path validation does require the maintained runtime:

  • Self-hosted Windows runner with LabVIEW 2025 Q3 installed and licensed
  • LVCompare at the canonical path: C:\Program Files\National Instruments\Shared\LabVIEW Compare\LVCompare.exe
  • LVCOMPARE_PATH or lvComparePath may be used only when they resolve to that canonical install location

Before broadening a consumer-facing change, read:

Getting Started

  • Fork and clone the repo
  • Branch from develop unless a maintainer runbook says otherwise
  • Keep changes narrow and update adjacent contract docs when supported behavior changes
  • Run the staging smoke helper before pushing:
    • pwsh -File tools/Test-PRVIStagingSmoke.ps1 -DryRun to preview the plan
    • node tools/npm/run-script.mjs smoke:vi-stage to run end-to-end using the baked-in fixtures/vi-attr attribute diff All staging runs post a summary comment and upload vi-compare-manifest / vi-staging-XX.zip artifacts; check the comment for links.

If you are changing release, validation, or governance behavior, also consult:

Action Development Tips

  • The action is composite with pwsh steps; prefer small changes and test incrementally
  • Exit code mapping: 0 = no diff, 1 = diff; any other exit code should fail fast (outputs preserved)
  • Full CLI flags are passed through lvCompareArgs (quotes supported)
  • You can set working-directory to control relative path resolution for base and head

Documentation

We use a multi-document strategy for comprehensive coverage:

  • README.md - Quick start and basic usage (keep focused, ~600 lines max)
  • docs/USAGE_GUIDE.md - Advanced configuration and recipes
  • docs/DEVELOPER_GUIDE.md - Testing, building, and release process
  • docs/TROUBLESHOOTING.md - Common issues and solutions
  • docs/COMPARE_LOOP_MODULE.md - Loop mode details
  • docs/INTEGRATION_TESTS.md - Test prerequisites and setup
  • docs/TESTING_PATTERNS.md - Advanced test design patterns

Documentation Guidelines

  • Keep README focused on getting started quickly; move details to topic-specific guides
  • Cross-link between documents for easy navigation
  • When adding new features, update relevant guide documents
  • Keep examples copy-paste friendly and accurate
  • Document breaking changes prominently in README and CHANGELOG

Style and Validation

  • PRs are governed by the current GitHub rulesets, merge queue, and workflow inventory in docs/WORKFLOW_CRITICALITY_MAP.md
  • Treat validate.yml, release-critical workflows, and Tier 2 product validation workflows as the baseline confidence surface for supported changes
  • Use hosted validation for docs/policy/Node/workflow changes and the self-hosted compare lanes only when the change actually touches the compare runtime or release path
  • Keep README and usage-guide examples accurate and executable

Testing

See the Developer Guide for comprehensive testing information including:

  • Running unit tests
  • Running integration tests
  • Test dispatcher architecture
  • Continuous development workflow

Quick commands:

# Unit tests only
./Invoke-PesterTests.ps1

# Local execution-slice harness (lock + LV guard + fixture prep + dispatcher)
pwsh -NoLogo -NoProfile -File tools/Run-PesterExecutionOnly.Local.ps1

# Integration tests (requires LVCompare)
$env:LV_BASE_VI = 'VI1.vi'
$env:LV_HEAD_VI = 'VI2.vi'
./Invoke-PesterTests.ps1 -IntegrationMode include

Branch Protection and Merge Policy (Maintainers)

Treat GitHub rulesets and branch settings as the source of truth; do not use this file as a hard-coded list of required checks.

  • develop is the active integration branch for this repository
  • merge behavior may be mediated by the current merge-queue / ruleset configuration
  • required checks and workflow expectations should be kept aligned with:

Repository Topics (Maintainers)

  • Keep repository topics aligned with the current product/governance surface: ci-cd, github-actions, labview, lvcompare, release-governance, software-assurance, workflow-automation

Marketplace Listing (Maintainers)

  • Ensure action.yml name, description, and branding are correct (icon: git-merge, color: blue)
  • Publish the repository to GitHub Marketplace
  • Update README.md with a Marketplace link after publication

Releases

  • Stable releases follow the active v0.6.x support line; release candidates use v0.6.x-rc tags until stable promotion
  • Keep package.json, backend version surfaces, CHANGELOG.md, and checked-in release helper docs aligned when a release candidate or stable cut is published
  • Use the current release runbooks/helpers rather than ad hoc tagging:
  • After a stable tag is published, ensure README examples reference the latest stable supported tag

Maintainers

Git hooks & multi-plane validation

Standing priority workflow

  • node tools/npm/run-script.mjs priority:bootstrap - detect the current plane, run hook preflight (and parity when --VerboseHooks is supplied), and refresh the standing-priority snapshot/router.
  • node tools/npm/run-script.mjs priority:handoff - ingest the latest handoff artifacts (issue-summary.json, issue-router.json, hook and watcher summaries) into the session, hydrating $StandingPrioritySnapshot, $StandingPriorityRouter, etc.
  • node tools/npm/run-script.mjs priority:handoff-tests - run the priority/hooks/semver checks and persist results to tests/results/_agent/handoff/test-summary.json for downstream agents.
  • node tools/npm/run-script.mjs priority:release - simulate the release actions described by the router; pass --Execute to run Branch-Orchestrator.ps1 -Execute instead of the default dry-run.
  • node tools/npm/run-script.mjs handoff:schema — validate the hook handoff summary (tests/results/_agent/handoff/hook-summary.json) against docs/schemas/handoff-hook-summary-v1.schema.json.
  • node tools/npm/run-script.mjs handoff:release-schema — validate the release summary (tests/results/_agent/handoff/release-summary.json) against docs/schemas/handoff-release-v1.schema.json.
  • node tools/npm/run-script.mjs semver:check — assert the current package.json version complies with SemVer 2.0 via tools/priority/validate-semver.mjs.

These helpers make the sandbox feel pseudo-persistent: each agent self-injects the previous session’s state before starting work and leaves updated artifacts when finishing.

  • The repository pins core.hooksPath=tools/hooks. Hooks are implemented as a Node core (tools/hooks/core/*.mjs) with thin shell/PowerShell shims so Linux, Windows, and CI all execute the same logic.

  • Hook summaries are written to tests/results/_hooks/<hook>.json and include exit codes, truncated stdout/stderr, and notes (e.g., when PowerShell is unavailable on Linux).

  • Run hook logic manually before committing/pushing:

    node tools/npm/run-script.mjs hooks:pre-commit
node tools/npm/run-script.mjs hooks:pre-push

    Passing HOOKS_PWSH=/path/to/pwsh or HOOKS_NODE=/path/to/node overrides discovery if needed.

  • Additional helpers:

    node tools/npm/run-script.mjs hooks:plane     # show detected plane + enforcement mode
node tools/npm/run-script.mjs hooks:preflight # verify dependencies for the current plane
node tools/npm/run-script.mjs hooks:multi     # run shell + PowerShell wrappers and diff JSON
node tools/npm/run-script.mjs hooks:schema    # validate summaries against the v1 schema

  • Control behaviour via HOOKS_ENFORCE=fail|warn|off (default: fail in CI, warn locally). Failures become warnings when enforcement is warn, and are suppressed entirely when set to off.

  • PowerShell-specific lint (inline-if, dot-sourcing, PSScriptAnalyzer) only runs when pwsh is available; otherwise the hook marks those steps as skipped and records a note in the summary.

  • The CI parity job ensures Windows and Linux shims stay in sync—if hook outputs drift, the workflow fails with a diff.

Documentation Style

Markdown lint configuration intentionally disables the MD013 (line length) rule globally. Rationale:

  • Technical tables, JSON fragments, and schema / command examples often exceed 160 chars and wrapping them reduces readability.
  • Large refactor risk: historical sections (dispatcher notes, loop mode tuning) rely on long inline code spans.

Guidelines:

  • Prefer wrapping narrative paragraphs to a reasonable width (~120–160) for new content, but do not hard-wrap within embedded JSON, PowerShell code fences, or tables.
  • Break up extremely long explanatory list items (>220 chars) unless doing so fragments a schema or command.
  • Use concise language; remove redundant qualifiers (e.g., "in order to" → "to").
  • Keep bullet introductions on their own line before long wrapped sub-lines for scanability.

When a single long line is clearer (e.g., a one-line JSON example), keep it—no inline disable needed since MD013 is off.

If we later re-enable MD013:

  1. Reintroduce a "MD013": { "line_length": 160 } block in .markdownlint.jsonc.
  2. Add per-line opt-outs using <!-- markdownlint-disable-next-line MD013 --> above intentional long lines.
  3. Avoid splitting code spans across lines solely for lint; prefer disabling for that line.

Always ensure examples remain copy/paste friendly (avoid trailing spaces, stray prompts inside code blocks).