Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
51 lines (41 loc) · 2.62 KB

CONTRIBUTING.md

File metadata and controls

51 lines (41 loc) · 2.62 KB
Raw

Contributing to VCF Checker

VCF Checker is based on vCheck-vSphere by Alan Renouf and contributors, and targets PowerShell 7 + VMware Cloud Foundation 9.x exclusively.

Ground rules

  • PowerShell 7 + VCF 9 only. No Windows PowerShell 5.1 compatibility, no Windows-only APIs, no deprecated PowerCLI surfaces (ELM/AllLinked, vSAN Management SDK, esxcli where the vSphere SDK serves). Windows-only code is removed, not guarded.
  • All sources UTF-8; paths via Join-Path; plugins must return, never exit (an exit kills the entire run).
  • Never commit real environment names or credentials. Shipped config values are anonymized (*.example.local); real values belong in the git-ignored GlobalVariables.local.ps1 / VCHECK_* environment variables.
  • No dash punctuation in reader-facing text (docs, report strings): no em dash, no en dash, no spaced hyphen. Use a period, comma, colon or parentheses instead. Hyphens inside words (email-safe, vSphere-Client) are fine; code comments and log lines are exempt.

Writing a plugin

A plugin is a .ps1 in a Plugins/<NN Category>/ folder that writes finding objects to stdout and declares metadata variables: $Title, $Header, $Comments, $Display (Table/List/None), $Author, $PluginVersion, $PluginCategory, and $PluginTags (comma-separated: health, security, capacity, events, inventory, slow, ops; profiles in Profiles.psd1 filter on these).

Performance rules (enforced in review):

  • Consume the pre-collected inventory globals ($VM, $VMH, $FullVM, $HostsViews, $Clusters, $Datastores, $clusviews, $storageviews). Never re-query them.
  • Batch Get-Stat and event queries across the inventory, never one call per VM/host.
  • Avoid esxcli software.* (~5 s framework overhead per invocation); prefer the vSphere SDK; other esxcli namespaces are fine.
  • Report problems only: empty output = no section in the report. Informational output belongs behind the inventory tag.

File naming: NNN Short Title.ps1: three digits, step 5 within the folder, order = execution order. Disable a plugin by appending .disabled to the filename.

Before you push

pwsh ./Tests/Invoke-Lint.ps1    # parse + PSScriptAnalyzer, must be clean
pwsh ./Tests/Invoke-Tests.ps1   # Pester suite (also runs in CI)

Plus a live pwsh ./vCheck.ps1 run against a VCF 9 environment for anything that changes plugin output. Commit per logical change with a descriptive message. When tagging a release, bump $vCheckVersion in vCheck.ps1 to match (it renders in the report footer).