PowerShellOrg · psjamesp · Apr 21, 2026 · Apr 21, 2026
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,135 @@
+# Contributing to PowerShellOrg Projects
+
+Welcome — and thank you for considering a contribution. PowerShellOrg maintains PowerShell open-source tools that depend on community involvement to survive. Every bug report, doc fix, and pull request matters.
+
+This document covers org-wide expectations. Individual repos may add project-specific guidance in their own `README.md` or `CONTRIBUTING.md`; where they conflict with this document, the repo-level doc takes precedence.
+
+---
+
+## Scope and governance
+
+PowerShellOrg focuses on PowerShell tooling. Before proposing a large feature or a significant design change, read [GOVERNANCE.md](GOVERNANCE.md) to understand how decisions get made. For substantial proposals, open an issue first so we can align before you invest time writing code.
+
+---
+
+## Before you contribute
+
+1. **Check existing issues and PRs.** Someone may already be working on it.
+2. **Read the repo's README.** Each project documents its purpose, status, and any project-specific constraints.
+3. **Agree to the license terms.** By submitting a contribution you agree that your work is licensed under the repo's license (MIT unless noted otherwise). See [License by contribution](#license-by-contribution) below.
+
+---
+
+## Development setup
+
+All PowerShellOrg projects use the same build stack:
+
+| Tool | Purpose |
+|---|---|
+| [psake](https://github.com/psake/psake) | Build automation |
+| [PowerShellBuild](https://github.com/psake/PowerShellBuild) | Shared psake task library |
+| [Pester 5](https://pester.dev) | Testing |
+| [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) | Static analysis |
+
+**Install build dependencies:**
+
+```powershell
+Install-Module psake             -Scope CurrentUser -Force
+Install-Module PowerShellBuild   -Scope CurrentUser -Force
+Install-Module Pester            -Scope CurrentUser -Force -MinimumVersion '5.0'
+Install-Module PSScriptAnalyzer  -Scope CurrentUser -Force
+```
+
+**Common psake tasks** (every repo exposes these):
+
+```powershell
+Invoke-psake Init      # First-time setup
+Invoke-psake Clean     # Remove build artifacts
+Invoke-psake Build     # Compile / stage the module
+Invoke-psake Test      # Run Pester tests
+Invoke-psake Analyze   # Run PSScriptAnalyzer
+Invoke-psake Publish   # Publish to PSGallery (maintainers only)
+```
+
+Run `Invoke-psake ?` to see all available tasks and their descriptions.
+
+**Target platforms:** Windows PowerShell 5.1 and PowerShell 7.x on Windows, Linux, and macOS. Write code that runs on all six combinations.
+
+---
+
+## Branching and commits
+
+- **Fork the repo** and work on a branch named for the thing you're changing: `fix/null-ref-in-invoke`, `feat/add-verbose-output`, `docs/update-readme`.
+- **Keep commits focused.** One logical change per commit. Use the [Conventional Commits](https://www.conventionalcommits.org/) style:
+  - `fix: correct null reference in Invoke-PSDepend`
+  - `feat: add -WhatIf support to Install task`
+  - `docs: clarify quickstart example`
+  - `chore: bump Pester to 5.6`
+  - `test: add coverage for empty dependency file`
+- **Do not squash history prematurely.** Maintainers may squash on merge if appropriate.
+- **Keep `main` green.** Never force-push to `main` or shared branches.
+
+---
+
+## Pull request expectations
+
+Before opening a PR:
+
+- [ ] `Invoke-psake Test` passes locally on at least one platform
+- [ ] `Invoke-psake Analyze` passes with no new warnings
+- [ ] New behavior has Pester test coverage
+- [ ] `CHANGELOG.md` is updated for user-facing changes
+- [ ] Docs are updated if behavior changed
+
+Fill out the PR template completely. PRs with empty templates or no linked issue for non-trivial changes will be asked to complete the template before review starts.
+
+**Draft PRs** are welcome for early feedback. Mark them ready for review when you want the full review pass.
+
+---
+
+## Code review expectations
+
+### For contributors
+
+- Respond to review comments within **14 days**. If you need more time, say so — we will wait.
+- If a comment is a question, answer it. If it is a request, either make the change or explain why you disagree.
+- A maintainer will make the final call. Disagreements are discussed, not escalated.
+
+### For maintainers
+
+| Repo status | First response SLA | Review completion SLA |
+|---|---|---|
+| `status-active` | 7 days | 30 days |
+| `status-stable` | 30 days | 60 days |
+
+SLAs are best-effort commitments, not guarantees. If a repo is understaffed, the Steward will note this in the repo's README.
+
+If a PR sits without response past the SLA, ping `@PowerShellOrg/maintainers` or open a discussion.
+
+---
+
+## Releases
+
+Releases are cut by maintainers. The process:
+
+1. Maintainer updates `CHANGELOG.md` and bumps the module version in the manifest.
+2. Maintainer opens a PR titled `chore: release vX.Y.Z`.
+3. PR is reviewed and merged to `main`.
+4. Maintainer pushes a version tag (`vX.Y.Z`) to `main`.
+5. The tag triggers `powershell-release.yml`, which builds, publishes to PSGallery, and creates a GitHub Release.
+
+Contributors do not cut releases. If you believe a release is overdue, open an issue and tag the maintainers.
+
+---
+
+## License by contribution
+
+By submitting a pull request or other contribution, you agree that your contribution is made under the same license as the project you are contributing to (MIT unless the repo states otherwise). You represent that you have the right to make the contribution under those terms.
+
+If your employer has rights to code you write, ensure you have permission to contribute it before submitting.
+
+---
+
+## Questions?
+
+See [SUPPORT.md](SUPPORT.md).
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,10 @@
+# PowerShellOrg funding configuration
+#
+# Uncomment and fill in the appropriate platform(s) if/when sponsorship
+# is set up. See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
+#
+# github:          # GitHub Sponsors username(s)
+# open_collective: # Open Collective handle
+# ko_fi:           # Ko-fi username
+# tidelift:        # Tidelift package name (e.g. npm/package-name)
+# custom:          # Array of custom sponsorship URLs
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -0,0 +1,107 @@
+# Security Policy
+
+## Supported versions
+
+By default, PowerShellOrg supports the **latest minor release of the latest major version** of each module. Individual repositories may define a broader support window in their own `SECURITY.md`; where they do, the repo-level policy takes precedence over this document.
+
+| Version policy | Receives security fixes? |
+|---|---|
+| Latest release | Yes |
+| Previous minor (same major) | Best-effort; patch may not be backported |
+| Older majors | No |
+
+If you are unsure whether a version is covered, open a discussion or check the repo's own `SECURITY.md`.
+
+---
+
+## Reporting a vulnerability
+
+**Please do not report security vulnerabilities in public GitHub issues.**
+
+### Preferred method: GitHub Private Vulnerability Reporting
+
+Use GitHub's built-in [Private Vulnerability Reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) on the affected repository:
+
+1. Navigate to the repository on GitHub.
+2. Click **Security** → **Advisories** → **Report a vulnerability**.
+3. Fill in the form with as much detail as you can provide.
+
+This creates an encrypted draft security advisory visible only to maintainers and the Steward.
+
+### Fallback method: email
+
+If GitHub Private Vulnerability Reporting is unavailable or you prefer email:
+
+**`security@powershellorg.example`** — `<FILL IN: replace with real address before publishing>`
+
+Encrypt your report with our PGP key if possible: `<FILL IN: PGP key fingerprint or link, or remove this line if not using PGP>`
+
+### What to include
+
+A useful report includes:
+
+- A description of the vulnerability and the potential impact
+- The affected module name(s) and version(s)
+- Steps to reproduce or a proof-of-concept
+- Any known mitigations or workarounds
+- Your preferred contact method for follow-up
+
+---
+
+## Our commitments
+
+Once we receive your report:
+
+| Milestone | Target |
+|---|---|
+| Acknowledge receipt | 72 hours |
+| Provide a status update | 7 days |
+| Deliver fix or mitigation for **critical** severity | 14 days |
+| Deliver fix or mitigation for **high** severity | 30 days |
+| Deliver fix or mitigation for **medium/low** severity | 90 days |
+
+These are targets, not guarantees. If we need more time, we will tell you why.
+
+---
+
+## Coordinated disclosure
+
+We follow a coordinated disclosure model:
+
+1. Reporter submits the vulnerability privately.
+2. Maintainers validate and develop a fix.
+3. We agree on an embargo period (typically 14–90 days depending on severity and fix complexity).
+4. A patched release is published.
+5. A GitHub Security Advisory is published, credited to the reporter unless they prefer to remain anonymous.
+6. For serious vulnerabilities we will request a CVE from a CNA; this typically happens at or before public disclosure.
+
+We ask that reporters:
+
+- Allow us the agreed embargo window before public disclosure
+- Avoid exploiting the vulnerability beyond what is needed to demonstrate it
+- Avoid accessing or modifying data belonging to others
+
+In return, we commit to:
+
+- Keeping you informed throughout the process
+- Crediting you in the advisory and release notes (unless you prefer anonymity)
+- Acting in good faith to resolve the issue promptly
+
+---
+
+## Out of scope
+
+The following are generally not in scope for security reports:
+
+- Vulnerabilities in PowerShell itself, the .NET runtime, or Windows — report those to Microsoft
+- Issues that require the attacker to already have administrative or write access to the affected system
+- Denial-of-service attacks that require significant resources from the attacker
+- Social engineering of maintainers or contributors
+
+If you are unsure whether your finding is in scope, report it anyway — we would rather review a borderline finding than miss a real one.
+
+---
+
+## Questions
+
+General security questions (not vulnerability reports) can be asked in GitHub Discussions on the relevant repository.
diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md
@@ -0,0 +1,40 @@
+# Getting Support
+
+## Where to ask questions
+
+**Use GitHub Discussions** for questions, how-to help, and general conversation about a project. Discussions are indexed by search engines, so your question and its answer may help future users.
+
+To ask a question:
+
+1. Navigate to the repository for the specific module you need help with.
+2. Click **Discussions** → **New discussion** → choose the **Q&A** category.
+3. Search existing discussions first — your question may already be answered.
+
+## Where to report bugs
+
+**Use GitHub Issues** for bugs: behavior that is clearly wrong, crashes, regressions, or documentation errors.
+
+Before opening a bug:
+
+- Check the existing issues (open and closed) for duplicates.
+- Confirm you are using the latest release.
+- Use the **Bug Report** issue template and fill it in completely.
+
+Incomplete bug reports (missing version, no reproduction steps) will be asked to provide more information before investigation begins.
+
+## Where NOT to ask
+
+- **Do not** open a GitHub Issue to ask a how-to question. Issues are for tracked work, not support conversations. How-to issues will be redirected to Discussions.
+- **Do not** email maintainers directly for support. Maintainers are volunteers; email bypasses the community who might also be able to help.
+
+## Security vulnerabilities
+
+Do **not** report security vulnerabilities in public issues or discussions. See [SECURITY.md](SECURITY.md) for the responsible disclosure process.
+
+## Response times
+
+Response times depend on the repository's lifecycle state. See [CONTRIBUTING.md](CONTRIBUTING.md) for current SLAs. PowerShellOrg projects are maintained by volunteers; we appreciate your patience.
+
+## Contributing a fix
+
+If you have found a bug and want to fix it yourself, that is always welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.