diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index a4aeb02..1f2a2d3 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -92,7 +92,7 @@ report it. You will not be retaliated against for making a good-faith report. **Primary contact:** -**Alternate contact:** Direct message to the Steward via GitHub or Discord. +**Alternate contact:** Direct message to the Org Admin via GitHub or Discord. When reporting, please include: @@ -112,13 +112,13 @@ required by law. ## Addressing and Repairing Harm -When a Code of Conduct violation is reported, the Steward (with input from the +When a Code of Conduct violation is reported, the Org Admin (with input from the Council where appropriate) will determine an appropriate response. Our goal is to address harm, support those affected, and where possible find a path for the person who caused harm to repair the relationship and reintegrate into the community. -The following is a guideline. The Steward retains discretion to apply responses +The following is a guideline. The Org Admin retains discretion to apply responses appropriate to the specific situation, including responses not listed here. ### 1. Private Conversation @@ -126,7 +126,7 @@ appropriate to the specific situation, including responses not listed here. **Community impact:** Use of inappropriate language, a single instance of unprofessional behavior, or behavior that, while not severe, was unwelcome. -**Response:** A private written communication from the Steward, providing +**Response:** A private written communication from the Org Admin, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. @@ -165,7 +165,7 @@ community. ## Restorative Paths -Where appropriate, and at the discretion of the Steward and the affected +Where appropriate, and at the discretion of the Org Admin and the affected parties, we may offer paths for community members who have caused harm to repair the relationship and re-engage with the community. This may include: @@ -180,13 +180,13 @@ limited to harassment, doxxing, threats of violence, or sexual misconduct. ## Appeals A person who has been subject to enforcement action may appeal the decision by -writing to the Steward within 30 days. The Steward will review the appeal with -input from the Council and respond within 30 days. +writing to the Org Admin within 30 days. The Org Admin will review the appeal +with input from the Council and respond within 30 days. -If the appeal involves the Steward's own decision and the appellant believes the -Steward cannot review it impartially, they may request that the Council review -the appeal collectively. In that case, the Council reviews and decides by -majority, and the Steward does not vote. +If the appeal involves the Org Admin's own decision and the appellant believes +the Org Admin cannot review it impartially, they may request that the Council +review the appeal collectively. In that case, the Council reviews and decides by +majority, and the Org Admin does not vote. ## Attribution @@ -202,4 +202,4 @@ For answers to common questions about this Code of Conduct, see the FAQ at --- -*Last updated: 2026/04/21. Reports go to .* +_Last updated: 2026/04/21. Reports go to ._ diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 44bc986..4acf431 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,22 +1,32 @@ # 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. +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. +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. +PowerShellOrg focuses on PowerShell tooling. Before proposing a large feature or +a significant design change, read [GOVERNANCE.md][governance] 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. +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. --- @@ -24,12 +34,12 @@ PowerShellOrg focuses on PowerShell tooling. Before proposing a large feature or 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 | +| Tool | Purpose | +| ------------------------------------ | ------------------------- | +| [psake][psake] | Build automation | +| [PowerShellBuild][powershellbuild] | Shared psake task library | +| [Pester 5][pester] | Testing | +| [PSScriptAnalyzer][psscriptanalyzer] | Static analysis | **Install build dependencies:** @@ -48,25 +58,29 @@ 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) +Invoke-psake Publish # Publish to PSGallery (CI only — never run manually) ``` 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. +**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: +- **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][conventional-commits] 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. +- **Do not squash history prematurely.** Maintainers may squash on merge if + appropriate. - **Keep `main` green.** Never force-push to `main` or shared branches. --- @@ -81,9 +95,12 @@ Before opening a PR: - [ ] `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. +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. +**Draft PRs** are welcome for early feedback. Mark them ready for review when +you want the full review pass. --- @@ -91,20 +108,26 @@ Fill out the PR template completely. PRs with empty templates or no linked issue ### 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. +- 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 | +| Repo status | First response SLA | Review completion SLA | +| --------------- | -------------------------------------------- | --------------------- | +| `status-active` | 7 days | 30 days | +| `status-stable` | 30 days | 60 days | +| `status-paused` | Suspended; security issues only, best-effort | — | -SLAs are best-effort commitments, not guarantees. If a repo is understaffed, the Steward will note this in the repo's README. +SLAs are best-effort commitments, not guarantees. If a repo is understaffed, the +project's 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. +If a PR sits without response past the SLA, open a discussion on the relevant +repository. --- @@ -112,24 +135,39 @@ If a PR sits without response past the SLA, ping `@PowerShellOrg/maintainers` or Releases are cut by maintainers. The process: -1. Maintainer updates `CHANGELOG.md` and bumps the module version in the manifest. +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. +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. +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. +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. +If your employer has rights to code you write, ensure you have permission to +contribute it before submitting. --- ## Questions? -See [SUPPORT.md](SUPPORT.md). +See [SUPPORT.md][support]. + +[governance]: GOVERNANCE.md +[psake]: https://github.com/psake/psake +[powershellbuild]: https://github.com/psake/PowerShellBuild +[pester]: https://pester.dev +[psscriptanalyzer]: https://github.com/PowerShell/PSScriptAnalyzer +[conventional-commits]: https://www.conventionalcommits.org/ +[support]: SUPPORT.md diff --git a/.github/DISCUSSION_TEMPLATE/announcements.yml b/.github/DISCUSSION_TEMPLATE/announcements.yml index 6999536..6899680 100644 --- a/.github/DISCUSSION_TEMPLATE/announcements.yml +++ b/.github/DISCUSSION_TEMPLATE/announcements.yml @@ -7,7 +7,7 @@ body: value: | Use this template for official announcements: new releases, adoption news, governance changes, maintainer changes, or other org-wide updates. - Only maintainers and the Steward should post in this category. Community members can react and reply. + Only maintainers, project Stewards, and the Org Admin should post in this category. Community members can react and reply. - type: textarea id: announcement diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md index 6217363..404325e 100644 --- a/.github/GOVERNANCE.md +++ b/.github/GOVERNANCE.md @@ -9,44 +9,72 @@ foundation. Speed and clarity matter more than process. ## Roles -### Steward +### Org Admin -One person. The Steward is the org's tiebreaker, external face, and -direction-setter. +One person. The Org Admin is the organization's tiebreaker for org-wide matters +and the external face of PowerShellOrg. Responsibilities: - Holds the GitHub org admin role - Owns the PowerShell Gallery account that issues per-repo scoped API keys -- Decides contested questions with input from the Council +- Decides contested org-wide questions with input from the Council - Represents PowerShellOrg externally - Maintains the private API key tracking record +- Approves adoptions, graduations, archival, governance changes, and Code of + Conduct changes -The role is named ("Steward of PowerShellOrg") rather than tied to an individual -so that succession is possible without renaming the role. +The role is named ("Org Admin of PowerShellOrg") rather than tied to an +individual so that succession is possible without renaming the role. + +### Steward (per project) + +One person per adopted project. The Steward is the tiebreaker _for that project_ +and drives it through its lifecycle. + +Responsibilities: + +- Owns the direction of the project +- Makes the final call on contested project-level decisions with input from the + project's maintainers +- Drives the revival playbook from adoption through to the first clean release +- Represents the project publicly (release announcements, blog posts, conference + talks where applicable) +- Proposes graduation when the project meets the criteria +- Flags to the Org Admin when the project needs help, when the Steward needs to + step down, or when the project should be archived + +Every adopted project must have a committed Steward at the time of adoption. +Projects without a Steward are not adopted. A project that loses its Steward +enters a 30-day find-a-replacement window (see below). + +The Steward is not required to be the original author of the tool, nor the +person who submitted the adoption request — though in practice it will often be +one or the other. ### Council -Up to seven people. Active maintainers across the org's repositories. +The cross-project body. Composed of all current Stewards, plus any additional +members the Org Admin invites for cross-cutting work (CI infrastructure, +security response, documentation). -By default, one Council seat per actively-maintained repository. The Steward may -invite additional members for cross-cutting work (CI infrastructure, security -response, documentation). The Council's role is **input, not consensus** — they -raise issues, propose changes, review adoption requests, and surface concerns. -The Steward decides. +The Council's role is **input, not consensus.** They raise issues, propose +changes, review adoption requests, and surface concerns. The Org Admin decides +org-wide matters; individual Stewards decide project-level matters. Council members are expected to: - Be reachable on the Council channel - Respond to adoption requests and governance proposals within the comment window -- Flag concerns about other maintainers, repositories, or the direction of the - org +- Flag concerns about other projects, maintainers, or the direction of the org +- Share context across projects so lessons from one revival inform the next -### Maintainer +### Maintainer (per repository) -Per-repository role. Has write access to a specific repository, can merge pull -requests, can cut releases. +Has write access to a specific repository, can merge pull requests, can cut +releases. The Steward of a project is always a maintainer on that project; +additional maintainers are added per the rules below. Maintainers are added per-repo, not org-wide. A maintainer on one repository has no special standing on others. @@ -58,24 +86,35 @@ permissions; recognition only. ## How decisions get made -**Default: Steward decides with Council input.** Speed is the explicit priority. +### Org-wide decisions + +**Org Admin decides with Council input.** Speed is the explicit priority. -For non-urgent decisions, the Steward will normally: +For non-urgent org-wide decisions, the Org Admin will normally: 1. Post a "thinking about doing X" note in the Council channel 2. Wait 72 hours for input 3. Act -Silence is assent. The Steward may act immediately for urgent matters and post +Silence is assent. The Org Admin may act immediately for urgent matters and post the rationale afterward. +### Project-level decisions + +**Steward decides with input from the project's maintainers.** Same 72-hour +silent-assent pattern by default, though Stewards may compress the window for +routine calls. The Org Admin does not override project-level decisions except +where they conflict with org-wide policy, the Code of Conduct, or the standard +build stack. + ### Decisions that require Council input before action -The Steward may not act unilaterally on these. Each requires a posted proposal +The Org Admin may not act unilaterally on these. Each requires a posted proposal and a comment window before action. - Adopting a new tool into the org -- Adding or removing a maintainer +- Appointing a new Steward (at adoption, or to fill a vacancy) +- Removing a Steward for cause - Graduating a tool to the `stable` lifecycle state - Archiving or deprecating a tool - Changing this governance document @@ -85,85 +124,143 @@ and a comment window before action. Comment windows: - Adoption decisions: 7 to 30 days from the adoption request being filed -- Maintainer changes: 72 hours +- Steward appointment to fill a vacancy: 72 hours +- Steward removal for cause: 72 hours - Graduation: 7 days - Archival: 30 days - Governance, Code of Conduct, or standard stack changes: 14 days +### Decisions at Steward discretion + +Within a project, the Steward has full discretion over: + +- Technical direction and roadmap +- Adding or removing co-maintainers on the project +- Release cadence (within the standard pipeline) +- Project-specific contributing guidelines that supplement the org-wide ones +- Day-to-day project operations + ### Decisions at maintainer discretion Within a repository, maintainers have full discretion over: - Routine pull request review and merge -- Releases (within the standard pipeline) +- Releases (within the standard pipeline, with Steward awareness) - Issue triage and labeling -- Day-to-day technical direction -- Repository-specific contributing guidelines that supplement the org-wide ones +- Responses to contributors + +## How Stewards are appointed + +**At adoption.** Every adoption request must identify a committed Steward. This +is typically: + +- The adoption submitter themselves, or +- A Council member who has volunteered to take on the project, or +- Someone the submitter has recruited and who has confirmed willingness + +If no Steward can be committed at the time of adoption, the adoption is not +approved. The request may remain open while a Steward is sought. + +The Org Admin confirms the Steward as part of the adoption decision, after +Council input. + +**To fill a vacancy.** If a Steward departs, the Org Admin opens a call for a +replacement on the Council channel. Candidates nominate themselves or are +nominated by a Council member. The Org Admin appoints after a 72-hour Council +comment window. + +## How Stewards depart + +**Self-departure.** Any Steward can step down at any time by notifying the Org +Admin and Council. They are thanked, their write access is preserved if they +wish to continue as a contributor or maintainer, and the Org Admin opens a call +for a replacement. + +**Vacancy window.** When a Steward departs, the project enters a 30-day vacancy +window. During this window, the Org Admin works with the Council to identify a +replacement. If no replacement emerges in 30 days: + +- The project moves to a `status-paused` state (topic tag on the repo, notice on + the README) +- Releases and active development pause; security fixes may still be issued by + the Org Admin or a willing maintainer +- The project remains paused until either a Steward is found (resuming its prior + state) or archival is proposed (following the normal archival process) + +A paused project does not count against the Council's active roster, and its +previous Steward's Council seat is vacated. + +**Removal for cause.** Code of Conduct violation, security incident, or a +sustained pattern of behavior that damages the project or the org. This is an +Org Admin decision after 72 hours of Council input. We document the decision +privately for the Council and communicate it publicly only to the extent +necessary. ## How maintainers get added Three paths. -**Sustained contribution.** Several merged pull requests and demonstrated -judgment over weeks to months. An existing maintainer nominates the contributor -in the Council channel; the Steward confirms within 72 hours. +**Steward addition.** The Steward of a project may add co-maintainers at their +discretion. This is announced to the Council, not gated by it. -**Adoption.** When PowerShellOrg adopts a tool, the submitter is offered -maintainer status on that repository by default. This is part of the adoption -commitment. +**Sustained contribution.** Several merged pull requests and demonstrated +judgment over weeks to months, identified by the Steward or another maintainer. -**Steward appointment.** For repositories with no active maintainer (typically -newly adopted or a maintainer departure), the Steward can directly appoint -someone willing to take it on. This is announced to the Council, not gated by -it. +**Adoption.** When a tool is adopted, the submitter is offered maintainer status +on that repository by default, regardless of whether they are also the Steward. ## How maintainers get removed Three paths. All preserve the contributor's commit history and credit. **Self-departure.** Anyone can step down at any time. We thank them, remove -access, archive their context, and move on. No questions asked. +access, and move on. No questions asked. **Inactivity.** No commits, reviews, or Council participation for nine months -triggers a Steward check-in. No response within thirty days of that check-in +triggers a check-in from the project's Steward. No response within thirty days results in write access being removed. Access can be reinstated at any time on request. **For cause.** Code of Conduct violation, security incident, or sustained -pattern of behavior that damages the project. This is a Steward decision after -Council input. We document the decision privately for the Council and -communicate it publicly only to the extent necessary. +pattern of behavior that damages the project. For co-maintainers this is a +Steward decision with Org Admin notification. For a Steward, see "Removal for +cause" above. -## Succession +## Succession for the Org Admin -If the Steward steps down, the Council selects a new Steward by majority vote. -The outgoing Steward, if available, confirms the selection. +If the Org Admin steps down, the Council selects a new Org Admin by majority +vote. The outgoing Org Admin, if available, confirms the selection. -If the Steward becomes unavailable without stepping down (extended +If the Org Admin becomes unavailable without stepping down (extended unresponsiveness, incapacity), the Council may proceed with selection after a thirty-day attempt to reach them. The selection is documented publicly. -To make this resilient: the Steward designates a backup with org admin access at -all times. The backup is not formally the Steward but has the technical access -to keep operations running during a transition. +To make this resilient: the Org Admin designates a backup with GitHub org admin +access at all times. The backup is not formally the Org Admin but has the +technical access to keep operations running during a transition. The backup is +typically a sitting Steward with demonstrated reliability. ## Lifecycle states -Every repository in the org is in one of four lifecycle states, tracked via a +Every repository in the org is in one of five lifecycle states, tracked via a topic tag on the repository. **`status-incoming`** — Just adopted, working through the revival playbook. Time-bounded; should not exceed 90 days. **`status-active`** — Default working state. Modernized build, clean releases, -responsive maintainership. First-response targets apply (7 days for issues and -PRs). +responsive Steward and maintainers. First-response targets apply (7 days for +issues and PRs). **`status-stable`** — Graduated. Mature, slow-changing tool that does not need active feature development. Stays in the org with reduced stewardship cadence. First-response target relaxes to 30 days. Security response time stays at the SECURITY.md baseline regardless of state. +**`status-paused`** — Steward vacancy in progress. No active development; +security-only maintenance if anyone is available. Resolves to `status-active`, +`status-stable`, or `status-archived` within a reasonable timeframe. + **`status-archived`** — No longer maintained. Repository is read-only on GitHub. PowerShell Gallery package is left in place (existing users would otherwise break) with a deprecation note added to the package description. @@ -183,8 +280,12 @@ Moving from `active` to `stable` requires all of the following to be true. failure) - Documentation reasonably complete -The repository's maintainers propose graduation in the Council channel. After a -7-day comment window, the Steward decides. +The project's Steward proposes graduation in the Council channel. After a 7-day +comment window, the Org Admin decides. + +A graduated project still has a Steward. The role's demands are lighter — fewer +active decisions, longer response windows — but the seat is not vacated simply +because the project reached `stable`. ### Archival process @@ -192,14 +293,16 @@ A repository may be considered for archival when any of the following is true. - No commits, releases, or substantive issue activity for 24 months - Superseded by a clearly better in-org or external tool -- No willing maintainer found after a 90-day open call +- No Steward found after a 90-day vacancy (extended from the normal 30-day + window at the Org Admin's discretion) - The original problem space no longer exists -The Steward proposes archival in the Council channel. After a 30-day comment -window, if no compelling objection is raised, the repository is archived: marked -read-only on GitHub, README updated to point at successors where applicable, -deprecation note added to the PowerShell Gallery package description, repository -topic tag updated to `status-archived`. +The Steward (or Org Admin, if the project is paused) proposes archival in the +Council channel. After a 30-day comment window, if no compelling objection is +raised, the repository is archived: marked read-only on GitHub, README updated +to point at successors where applicable, deprecation note added to the +PowerShell Gallery package description, repository topic tag updated to +`status-archived`. ## Scope @@ -212,14 +315,15 @@ Out of scope: maintenance - Single-vendor commercial tools - Anything that would compete with an active upstream maintainer -- Anything we do not have the bandwidth to actually maintain +- Anything without a willing Steward ## Changing this document Changes to this governance document follow the rules above: Council comment -window of 14 days, Steward decides. Material changes are announced on the org +window of 14 days, Org Admin decides. Material changes are announced on the org profile and in a pinned discussion. --- -*Last updated: 2026/04/21. Maintained by the Steward with input from the Council.* +_Last updated: 2026/04/21. Maintained by the Org Admin with input from the +Council._ diff --git a/.github/ISSUE_TEMPLATE/tool_adoption_request.yml b/.github/ISSUE_TEMPLATE/tool_adoption_request.yml index e2b7227..0376589 100644 --- a/.github/ISSUE_TEMPLATE/tool_adoption_request.yml +++ b/.github/ISSUE_TEMPLATE/tool_adoption_request.yml @@ -127,6 +127,32 @@ body: validations: required: true + - type: dropdown + id: steward-commitment + attributes: + label: Who will serve as Steward for this project? + description: > + Every adopted project must have a committed Steward — someone who owns the project's direction + and drives the revival playbook. This is a heavier commitment than co-maintainer. See the + adoption criteria for the full Steward commitment. + options: + - "I will be the Steward" + - "Another named person has committed (provide details in the field below)" + - "I'm hoping someone on the Council will volunteer" + validations: + required: true + + - type: textarea + id: steward-details + attributes: + label: Named Steward details + description: > + If you selected "Another named person has committed" above, provide their name and GitHub + handle here. Leave blank otherwise. + placeholder: "Name: \nGitHub handle: @" + validations: + required: false + - type: textarea id: additional-notes attributes: diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 5a53c37..5670f19 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -2,15 +2,19 @@ ## 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 | +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 | +| Older majors | No | -If you are unsure whether a version is covered, open a discussion or check the repo's own `SECURITY.md`. +If you are unsure whether a version is covered, open a discussion or check the +repo's own `SECURITY.md`. --- @@ -20,21 +24,21 @@ If you are unsure whether a version is covered, open a discussion or check the r ### 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: +Use GitHub's built-in [Private Vulnerability +Reporting][private-vulnerability-reporting] 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. +This creates an encrypted draft security advisory visible only to maintainers +and the Org Admin. ### Fallback method: email If GitHub Private Vulnerability Reporting is unavailable or you prefer email: -**`security@powershellorg.example`** — `` - -Encrypt your report with our PGP key if possible: `` +**** ### What to include @@ -52,13 +56,13 @@ A useful report includes: 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 | +| 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. @@ -70,10 +74,13 @@ 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). +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. +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: @@ -93,15 +100,22 @@ In return, we commit to: 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 +- 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. +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. +General security questions (not vulnerability reports) can be asked in GitHub +Discussions on the relevant repository. + +[private-vulnerability-reporting]: + https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index 401d807..4d370c2 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -2,7 +2,9 @@ ## 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. +**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: @@ -12,7 +14,8 @@ To ask a question: ## Where to report bugs -**Use GitHub Issues** for bugs: behavior that is clearly wrong, crashes, regressions, or documentation errors. +**Use GitHub Issues** for bugs: behavior that is clearly wrong, crashes, +regressions, or documentation errors. Before opening a bug: @@ -20,21 +23,32 @@ Before opening a bug: - 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. +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. +- **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. +Do **not** report security vulnerabilities in public issues or discussions. See +[SECURITY.md][security] 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. +Response times depend on the repository's lifecycle state. See +[CONTRIBUTING.md][contributing] 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. +If you have found a bug and want to fix it yourself, that is always welcome. See +[CONTRIBUTING.md][contributing] to get started. + +[security]: SECURITY.md +[contributing]: CONTRIBUTING.md diff --git a/README.md b/README.md index 2c7d406..51eb341 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,37 @@ # PowerShellOrg Community Health Files -This repository provides organization-wide default community health files and shared infrastructure for [PowerShellOrg](https://github.com/PowerShellOrg) — a community-run GitHub organization dedicated to maintaining quality PowerShell open-source tools. +This repository provides organization-wide default community health files and +shared infrastructure for [PowerShellOrg][powershellorg] — a community-run +GitHub organization dedicated to maintaining quality PowerShell open-source +tools. -GitHub automatically applies the files in `.github/` to every repository in the org that does not define its own version. +GitHub automatically applies the files in `.github/` to every repository in the +org that does not define its own version. ## What's in here -| Path | Purpose | -|---|---| -| [`.github/CODE_OF_CONDUCT.md`](.github/CODE_OF_CONDUCT.md) | Contributor Covenant 3.0, adapted for PowerShellOrg | -| [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) | Org-wide contribution guide; dev setup, PR expectations, release process | -| [`.github/SECURITY.md`](.github/SECURITY.md) | Vulnerability reporting policy and SLA commitments | -| [`.github/SUPPORT.md`](.github/SUPPORT.md) | Where to ask questions vs. file issues | -| [`.github/GOVERNANCE.md`](.github/GOVERNANCE.md) | Roles, decision-making, maintainer lifecycle, succession | -| [`.github/FUNDING.yml`](.github/FUNDING.yml) | Funding platform configuration (placeholder) | -| [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) | YAML issue forms: bug, feature, question, adoption request | -| [`.github/DISCUSSION_TEMPLATE/`](.github/DISCUSSION_TEMPLATE/) | Discussion category starters | -| [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) | Standard PR checklist | -| [`.github/workflows/powershell-ci.yml`](.github/workflows/powershell-ci.yml) | Reusable CI workflow: Windows + Linux + macOS, PS 5.1 + 7.x | -| [`.github/workflows/powershell-release.yml`](.github/workflows/powershell-release.yml) | Reusable release workflow: build, publish to PSGallery, GitHub Release | -| [`docs/maintainer-onboarding.md`](docs/maintainer-onboarding.md) | Day-1 checklist for new maintainers | -| [`docs/revival-playbook.md`](docs/revival-playbook.md) | Five-phase checklist for reviving an abandoned tool | -| [`docs/adoption-criteria.md`](docs/adoption-criteria.md) | What we evaluate before adopting a tool | -| [`profile/README.md`](profile/README.md) | Org landing page displayed on github.com/PowerShellOrg | +| Path | Purpose | +| -------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [`.github/CODE_OF_CONDUCT.md`][code-of-conduct] | Contributor Covenant 3.0, adapted for PowerShellOrg | +| [`.github/CONTRIBUTING.md`][contributing] | Org-wide contribution guide; dev setup, PR expectations, release process | +| [`.github/SECURITY.md`][security] | Vulnerability reporting policy and SLA commitments | +| [`.github/SUPPORT.md`][support] | Where to ask questions vs. file issues | +| [`.github/GOVERNANCE.md`][governance] | Roles, decision-making, maintainer lifecycle, succession | +| [`.github/FUNDING.yml`][funding] | Funding platform configuration (placeholder) | +| [`.github/ISSUE_TEMPLATE/`][issue-template] | YAML issue forms: bug, feature, question, adoption request | +| [`.github/DISCUSSION_TEMPLATE/`][discussion-template] | Discussion category starters | +| [`.github/PULL_REQUEST_TEMPLATE.md`][pr-template] | Standard PR checklist | +| [`.github/workflows/powershell-ci.yml`][workflow-ci] | Reusable CI workflow: Windows + Linux + macOS, PS 5.1 + 7.x | +| [`.github/workflows/powershell-release.yml`][workflow-release] | Reusable release workflow: build, publish to PSGallery, GitHub Release | +| [`docs/maintainer-onboarding.md`][maintainer-onboarding] | Day-1 checklist for new maintainers | +| [`docs/revival-playbook.md`][revival-playbook] | Five-phase checklist for reviving an abandoned tool | +| [`docs/adoption-criteria.md`][adoption-criteria] | What we evaluate before adopting a tool | +| [`profile/README.md`][profile-readme] | Org landing page displayed on github.com/PowerShellOrg | ## Reusable workflows -Both workflows are [reusable](https://docs.github.com/en/actions/using-workflows/reusing-workflows) via `workflow_call`. Consuming repos call them from their own tag-triggered or push-triggered workflows. +Both workflows are [reusable][reusable-workflows] via `workflow_call`. Consuming +repos call them from their own tag-triggered or push-triggered workflows. **Current consumers:** Plaster, PSDepend @@ -42,7 +47,8 @@ jobs: ### Release (`powershell-release.yml`) -Builds, publishes to PSGallery, and creates a GitHub Release. Requires the `PSGALLERY_API_KEY` secret to be set in the consuming repo. +Builds, publishes to PSGallery, and creates a GitHub Release. Requires the +`PSGALLERY_API_KEY` secret to be set in the consuming repo. ```yaml jobs: @@ -56,8 +62,31 @@ jobs: ## Governance -See [`GOVERNANCE.md`](.github/GOVERNANCE.md) for the full governance model. The short version: Gilbert Sanchez is the Steward; the Council is all active maintainers; decisions default to the Steward with a 72-hour silent-assent window for non-urgent changes. +See [`GOVERNANCE.md`][governance] for the full governance model. The short +version: the Org Admin holds org-wide authority; each adopted project has its +own Steward who drives it day-to-day; the Council is all active Stewards plus +invited members; the 72-hour silent-assent window applies to both. ## License -[MIT](LICENSE) +[MIT][license] + +[powershellorg]: https://github.com/PowerShellOrg +[code-of-conduct]: .github/CODE_OF_CONDUCT.md +[contributing]: .github/CONTRIBUTING.md +[security]: .github/SECURITY.md +[support]: .github/SUPPORT.md +[governance]: .github/GOVERNANCE.md +[funding]: .github/FUNDING.yml +[issue-template]: .github/ISSUE_TEMPLATE/ +[discussion-template]: .github/DISCUSSION_TEMPLATE/ +[pr-template]: .github/PULL_REQUEST_TEMPLATE.md +[workflow-ci]: .github/workflows/powershell-ci.yml +[workflow-release]: .github/workflows/powershell-release.yml +[maintainer-onboarding]: docs/maintainer-onboarding.md +[revival-playbook]: docs/revival-playbook.md +[adoption-criteria]: docs/adoption-criteria.md +[profile-readme]: profile/README.md +[reusable-workflows]: + https://docs.github.com/en/actions/using-workflows/reusing-workflows +[license]: LICENSE diff --git a/docs/adoption-criteria.md b/docs/adoption-criteria.md index a75ae81..ef2e61e 100644 --- a/docs/adoption-criteria.md +++ b/docs/adoption-criteria.md @@ -1,116 +1,192 @@ # Adoption Criteria -This document describes how PowerShellOrg evaluates tools for adoption, what we commit to when we adopt something, and what the submitter commits to. +This document describes how PowerShellOrg evaluates tools for adoption, what we +commit to when we adopt something, and what the submitter commits to. -Read this before submitting a [Tool Adoption Request](https://github.com/PowerShellOrg/.github/issues/new?template=tool_adoption_request.yml). +Read this before submitting a [Tool Adoption Request]. --- ## Must-be-true criteria -All six of the following must be true before we will adopt a tool. These are not negotiable. +All six of the following must be true before we will adopt a tool. These are not +negotiable. ### 1. Open-source license -The tool must have an OSI-approved open-source license in place before or at the time of transfer. We strongly prefer MIT or Apache 2.0, which are compatible with the rest of the org's tooling and license stack. +The tool must have an OSI-approved open-source license in place before or at the +time of transfer. We strongly prefer MIT or Apache 2.0, which are compatible +with the rest of the org's tooling and license stack. -Tools with no license, or with proprietary or source-available licenses, are ineligible. If the original author is willing to relicense to MIT, that resolves the issue — we can help coordinate. +Tools with no license, or with proprietary or source-available licenses, are +ineligible. If the original author is willing to relicense to MIT, that resolves +the issue — we can help coordinate. ### 2. Author consent or demonstrated abandonment We do not take over maintained projects without permission. -- **If the original author is reachable and active:** We require explicit written consent (a GitHub comment, email, or issue) from the author or all current maintainers. This protects them and protects us. -- **If the project appears abandoned:** We require documented evidence that we made a reasonable good-faith effort to reach the author (GitHub @-mention, issue opened, email to the address in the git log or package metadata) and received no response after at least 30 days. +- **If the original author is reachable and active:** We require explicit + written consent (a GitHub comment, email, or issue) from the author or all + current maintainers. This protects them and protects us. +- **If the project appears abandoned:** We require documented evidence that we + made a reasonable good-faith effort to reach the author (GitHub @-mention, + issue opened, email to the address in the git log or package metadata) and + received no response after at least 30 days. -When in doubt, we wait. Burning bridges with the original author is not worth any single tool. +When in doubt, we wait. Burning bridges with the original author is not worth +any single tool. ### 3. Real user base -The tool must have evidence of real-world use: PSGallery downloads, GitHub stars/forks, dependent projects, forum mentions, or other signals that someone besides the submitter relies on it. +The tool must have evidence of real-world use: PSGallery downloads, GitHub +stars/forks, dependent projects, forum mentions, or other signals that someone +besides the submitter relies on it. -We will not adopt a tool that has no users outside its author, because there would be no one to maintain it for. +We will not adopt a tool that has no users outside its author, because there +would be no one to maintain it for. ### 4. Manageable scope -The tool's maintenance burden must be sustainable given the org's current maintainer pool. We consider: +The tool's maintenance burden must be sustainable given the org's current +maintainer pool. We consider: - Lines of code and architectural complexity -- Test coverage and CI state (a tool with no tests requires significant upfront investment) +- Test coverage and CI state (a tool with no tests requires significant upfront + investment) - Open issue and PR backlog - Dependency footprint -We will not adopt a tool if doing so would overextend our maintainers. We would rather maintain a smaller number of tools well than a large number poorly. +We will not adopt a tool if doing so would overextend our maintainers. We would +rather maintain a smaller number of tools well than a large number poorly. ### 5. No unaddressed security issues -We will not inherit a tool with known, unaddressed security vulnerabilities. Before adoption, the submitter must either: +We will not inherit a tool with known, unaddressed security vulnerabilities. +Before adoption, the submitter must either: - Confirm there are no known security issues, or -- Document all known issues and commit to addressing them in the first release cycle +- Document all known issues and commit to addressing them in the first release + cycle -This is not about perfection — it is about not knowingly shipping something unsafe to our users. +This is not about perfection — it is about not knowingly shipping something +unsafe to our users. ### 6. No legal encumbrance -The tool must not carry legal risks that would expose PowerShellOrg or its maintainers. Examples of disqualifying encumbrances: +The tool must not carry legal risks that would expose PowerShellOrg or its +maintainers. Examples of disqualifying encumbrances: - Copyright claims from a third party - Code copied from a non-compatible license without attribution - Trademark issues - Export control restrictions +### 7. A committed Steward has been identified + +No Steward, no adoption. + +Every adoption request must name a person who has agreed to serve as the +project's Steward after transfer. The Steward does not need to be the submitter, +but someone must have explicitly committed to the role before the adoption is +approved. + +If no Steward can be confirmed at decision time, the adoption is deferred — not +declined. The request remains open while a Steward is sought. + --- ## What PowerShellOrg commits to When we adopt a tool, we commit to: -1. **Maintaining it actively** — responding to issues within our SLA, reviewing PRs, and cutting releases when there are meaningful changes -2. **Not abandoning it silently** — if we decide we cannot maintain a tool, we will announce it publicly and give the community 90 days to find alternative stewardship before archiving -3. **Keeping it open source** — the tool will remain under its existing OSI license (or a compatible one with explicit permission) -4. **Not breaking the API or CLI interface without a major version bump** — we respect existing users' scripts and pipelines -5. **Giving credit** — the original author's contributions remain in git history and are acknowledged in the CHANGELOG and package metadata -6. **Handling security responsibly** — following our published security policy for vulnerability disclosure and response +1. **Maintaining it actively** — responding to issues within our SLA, reviewing + PRs, and cutting releases when there are meaningful changes +2. **Not abandoning it silently** — if a project loses its Steward, we enter a + 30-day vacancy window and, if no replacement is found, move the project to + `status-paused` rather than archiving it immediately. A paused project can + resume when a new Steward steps up. Extended vacancies (90 days) may lead to + the normal archival process +3. **Keeping it open source** — the tool will remain under its existing OSI + license (or a compatible one with explicit permission) +4. **Not breaking the API or CLI interface without a major version bump** — we + respect existing users' scripts and pipelines +5. **Giving credit** — the original author's contributions remain in git history + and are acknowledged in the CHANGELOG and package metadata +6. **Handling security responsibly** — following our published security policy + for vulnerability disclosure and response --- ## What the submitter commits to -Adoption requests that do not include a maintainer commitment are evaluated more skeptically. A tool with no one willing to maintain it is a higher-risk adoption. - -If you are submitting a request and are willing to maintain the tool: - -1. **Minimum 6 months of active maintenance** — you will triage issues, review PRs, and be reachable for at least 6 months after adoption -2. **On-boarding and knowledge transfer** — you will work with the PowerShellOrg maintainer team to document the tool's internals, known issues, and quirks before stepping back -3. **Good-faith participation** — you will engage with the community, respond to review comments, and follow PowerShellOrg's contribution norms -4. **Transparency about limitations** — if you know the tool has problems, you will document them upfront rather than letting us discover them post-adoption - -We understand life happens. If you need to step back before the 6 months are up, tell us early — we will work with you. +Every submitter is asked to indicate whether they will serve as the project's +**Steward**, as a **co-maintainer**, or neither. The commitment differs +significantly between the two roles. + +### If you are serving as Steward + +The Steward commitment is heavier than a standard maintainer commitment. You are +committing to: + +1. **Driving the revival playbook** — you own the tracking issue and the + checklist through to the first clean release +2. **Project direction** — you make the final call on contested project-level + decisions and are the project's public face +3. **At least 12 months of active stewardship** — the 6-month minimum applies to + co-maintainers; as Steward you are expected to see the project through to + `status-active` and at least to the first graduation evaluation +4. **Transparency about limitations** — if you know the tool has problems, + document them upfront +5. **Early notice if you need to step down** — your departure triggers a 30-day + vacancy window; the earlier we know, the better for the project + +### If you are serving as co-maintainer (not Steward) + +1. **Minimum 6 months of active maintenance** — you will triage issues, review + PRs, and be reachable for at least 6 months after adoption +2. **On-boarding and knowledge transfer** — you will work with the PowerShellOrg + maintainer team to document the tool's internals, known issues, and quirks + before stepping back +3. **Good-faith participation** — you will engage with the community, respond to + review comments, and follow PowerShellOrg's contribution norms +4. **Transparency about limitations** — if you know the tool has problems, you + will document them upfront rather than letting us discover them post-adoption + +We understand life happens. If you need to step back before your commitment is +up, tell the project's Steward (or the Org Admin if you are the Steward) early — +we will work with you. --- ## The adoption workflow -| Step | Owner | Timeline | -|---|---|---| -| Submitter files a Tool Adoption Request | Submitter | — | -| Steward acknowledges the request and assigns it to the Council | Steward | 7 days | -| Council members review and comment | Council | 30 days | -| Steward makes a decision (adopt / decline / defer) | Steward | 30 days from submission | -| If adopted: repo transfer initiated, onboarding begins | Steward + submitter | Week of decision | -| Repo moves to `status-incoming`, Revival Playbook begins | Lead maintainer | Immediately after transfer | +| Step | Owner | Timeline | +| ------------------------------------------------------------------------------------------------ | --------------------- | -------------------------- | +| Submitter files a Tool Adoption Request | Submitter | — | +| Org Admin acknowledges the request and assigns it to the Council | Org Admin | 7 days | +| Council members review and comment | Council | 30 days | +| Org Admin makes a decision (adopt / decline / defer), confirming the Steward as part of adoption | Org Admin | 30 days from submission | +| If adopted: repo transfer initiated, onboarding begins | Org Admin + submitter | Week of decision | +| Repo moves to `status-incoming`, Revival Playbook begins | Steward | Immediately after transfer | ### What "declined" means -A declined adoption request is not a judgment on the tool's quality or the submitter's intentions. Common reasons for declining: +A declined adoption request is not a judgment on the tool's quality or the +submitter's intentions. Common reasons for declining: - The tool does not meet one of the must-be-true criteria - Our current maintainer pool cannot take it on right now - A better maintainer or org has already stepped up -We will always explain the reason. Declined requests may be resubmitted when circumstances change. +We will always explain the reason. Declined requests may be resubmitted when +circumstances change. ### What "deferred" means -A deferred request means we are interested but there is a blocker we need to resolve first — usually the license, the author consent, or maintainer capacity. We will set a follow-up date and reopen the discussion then. +A deferred request means we are interested but there is a blocker we need to +resolve first — usually the license, the author consent, or maintainer capacity. +We will set a follow-up date and reopen the discussion then. + +[Tool Adoption Request]: + https://github.com/PowerShellOrg/.github/issues/new?template=tool_adoption_request.yml diff --git a/docs/maintainer-onboarding.md b/docs/maintainer-onboarding.md index 4cb3d8c..b120816 100644 --- a/docs/maintainer-onboarding.md +++ b/docs/maintainer-onboarding.md @@ -1,6 +1,7 @@ # Maintainer Onboarding -Welcome to PowerShellOrg. This checklist walks you through everything you need to be fully operational on day one and productive in the first week. +Welcome to PowerShellOrg. This checklist walks you through everything you need +to be fully operational on day one and productive in the first week. --- @@ -8,19 +9,28 @@ Welcome to PowerShellOrg. This checklist walks you through everything you need t ### GitHub org access -- [ ] Accept the org invite from the Steward (check your GitHub notifications and email) -- [ ] Verify you have **Write** access to your assigned repo(s) — navigate to the repo → **Settings** → **Collaborators and teams** -- [ ] Enable **two-factor authentication** on your GitHub account if not already enabled — this is a hard requirement for org membership ([docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication)) +- [ ] Accept the org invite from the Org Admin (check your GitHub notifications + and email) +- [ ] Verify you have **Write** access to your assigned repo(s) — navigate to + the repo → **Settings** → **Collaborators and teams** +- [ ] Enable **two-factor authentication** on your GitHub account if not already + enabled — this is a hard requirement for org membership + ([docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication]) ### Council channel -- [ ] Introduce yourself in the Council channel: `` -- [ ] Note your timezone and typical availability (helps set realistic review expectations) +- [ ] Introduce yourself in the Council channel: + `` +- [ ] Note your timezone and typical availability (helps set realistic review + expectations) ### PSGallery account -- [ ] Confirm you have a [PowerShell Gallery](https://www.powershellgallery.com/) account -- [ ] Share your PSGallery username with the Steward — you will need it for the API key issuance step below +- [ ] Confirm you have a [PowerShell Gallery] account + +Note: you do not need personal PSGallery publishing credentials. All releases go +through GitHub Actions CI using a scoped API key stored in the repo's Actions +secrets. You never run `Invoke-psake Publish` locally. --- @@ -29,58 +39,73 @@ Welcome to PowerShellOrg. This checklist walks you through everything you need t - [ ] Clone the repo locally - [ ] Read the repo's `README.md` and any existing `CONTRIBUTING.md` - [ ] Read `CHANGELOG.md` to understand recent history -- [ ] Read open issues and PRs — look for anything labeled `needs-triage` or with recent activity +- [ ] Read open issues and PRs — look for anything labeled `needs-triage` or + with recent activity --- ## Day 1: Branch protection verification -Verify the repo's default branch has the following protections enabled. Navigate to the repo → **Settings** → **Branches** → branch protection rule for `main`. +Verify the repo's default branch has the following protections enabled. Navigate +to the repo → **Settings** → **Branches** → branch protection rule for `main`. - [ ] **Require a pull request before merging** — enabled - [ ] **Require approvals** — at least 1 required reviewer -- [ ] **Dismiss stale pull request approvals when new commits are pushed** — enabled -- [ ] **Require status checks to pass before merging** — enabled; the CI workflow must be listed +- [ ] **Dismiss stale pull request approvals when new commits are pushed** — + enabled +- [ ] **Require status checks to pass before merging** — enabled; the CI + workflow must be listed - [ ] **Require branches to be up to date before merging** — enabled - [ ] **Require linear history** — enabled - [ ] **Do not allow force pushes** — enabled - [ ] **Do not allow deletions** — enabled -If any of these are missing, notify the Steward before merging anything. +If any of these are missing, notify the project's Steward before merging +anything. --- ## Day 1: PSGallery API key -PowerShellOrg uses **per-repo scoped API keys** for PSGallery. You do not get an org-wide key. +PowerShellOrg uses **per-repo scoped API keys** for PSGallery. You do not get an +org-wide key. + +### Key issuance process (Org Admin or Council action) -### Key issuance process (Steward action) +The Org Admin or a Council member creates the key with these parameters: -The Steward creates the key with these parameters: +| Parameter | Value | +| ------------ | ------------------------------------------------------------------------------ | +| Key name | `PowerShellOrg--` (e.g., `PowerShellOrg-PSDepend-2025-11`) | +| Glob pattern | The module name exactly (e.g., `PSDepend`) | +| Expiration | 365 days (the PSGallery maximum) | -| Parameter | Value | -|---|---| -| Key name | `PowerShellOrg--` (e.g., `PowerShellOrg-PSDepend-2025-11`) | -| Glob pattern | The module name exactly (e.g., `PSDepend`) | -| Expiration | 365 days (the PSGallery maximum) | +They then: -The Steward then: -1. Creates or updates the `PSGALLERY_API_KEY` Actions secret in the repo -2. Adds a rotation reminder to the private key tracking issue (pinned to this repo) -3. Notifies the maintainer that the key is in place +1. Set the `PSGALLERY_API_KEY` Actions secret in the repo +2. Add a rotation reminder to the Org Admin's private tracking issue +3. Notify the maintainer that the key is in place ### Maintainer steps -- [ ] Confirm with the Steward that `PSGALLERY_API_KEY` is set in the repo's Actions secrets (**Settings** → **Secrets and variables** → **Actions**) -- [ ] Note the key expiration month — the Steward will initiate rotation, but you may be asked to trigger it +- [ ] Confirm that `PSGALLERY_API_KEY` is set in the repo's Actions secrets + (**Settings** → **Secrets and variables** → **Actions**) +- [ ] Run a test release (pre-release tag) to verify the workflow succeeds + end-to-end + +If the release workflow ever fails with an authentication error, the key may +have expired — notify the Org Admin or Council; do not attempt to create or +rotate the key yourself. ### Key rotation -Keys expire after 365 days. The Steward tracks rotation in a private pinned issue. When rotation is due: -1. Steward creates a new key on PSGallery with the same glob, new `YYYY-MM` suffix in the name -2. Steward updates the `PSGALLERY_API_KEY` secret in the repo -3. Old key is deleted from PSGallery -4. Tracking issue is updated +Keys expire after 365 days. The Org Admin tracks rotation in a private pinned +issue. When rotation is due, the Org Admin or a Council member: + +1. Creates a new key on PSGallery with the same glob, new `YYYY-MM` suffix +2. Updates the `PSGALLERY_API_KEY` secret in the repo +3. Deletes the old key from PSGallery +4. Updates the tracking issue --- @@ -95,12 +120,15 @@ Keys expire after 365 days. The Steward tracks rotation in a private pinned issu Install-Module Pester -Scope CurrentUser -Force -MinimumVersion '5.0' -MaximumVersion '5.99' ``` -- [ ] Run `Invoke-psake ?` in the repo root — confirm the standard tasks are listed (Init, Clean, Build, Test, Analyze, Publish) +- [ ] Run `Invoke-psake ?` in the repo root — confirm the standard tasks are + listed (Init, Clean, Build, Test, Analyze, Publish) - [ ] Run `Invoke-psake Test` — confirm all tests pass - [ ] Run `Invoke-psake Analyze` — confirm no PSScriptAnalyzer warnings -- [ ] Navigate to the repo's **Actions** tab and confirm the CI workflow is running and green on `main` +- [ ] Navigate to the repo's **Actions** tab and confirm the CI workflow is + running and green on `main` -If the CI workflow is not present or not green, see the [Revival Playbook](revival-playbook.md) Phase 3 for modernization steps. +If the CI workflow is not present or not green, see the [Revival +Playbook][revival-playbook] Phase 3 for modernization steps. --- @@ -108,30 +136,74 @@ If the CI workflow is not present or not green, see the [Revival Playbook](reviv ### Issue and PR triage -| Repo status | First-response target | -|---|---| -| `status-active` | 7 days | -| `status-stable` | 30 days | +| Repo status | First-response target | +| --------------- | -------------------------------------------- | +| `status-active` | 7 days | +| `status-stable` | 30 days | +| `status-paused` | Suspended; security issues only, best-effort | -First response means: a label applied, a comment acknowledging the issue, or a review comment on the PR — not necessarily a resolution. +First response means: a label applied, a comment acknowledging the issue, or a +review comment on the PR — not necessarily a resolution. -Set up GitHub notifications for your repo: **Watch** → **All activity**, or at minimum **Issues** and **Pull requests**. +Set up GitHub notifications for your repo: **Watch** → **All activity**, or at +minimum **Issues** and **Pull requests**. ### Code review - Aim to complete (not just start) reviews within 30 days of assignment -- Use GitHub's "Request changes" only when a change is genuinely blocking — a comment thread is sufficient for most feedback -- When merging, prefer **Squash and merge** for single-commit PRs and **Merge commit** for multi-commit work where history is meaningful. Avoid **Rebase and merge** unless the branch is perfectly clean — it rewrites history and removes the merge traceability. +- Use GitHub's "Request changes" only when a change is genuinely blocking — a + comment thread is sufficient for most feedback +- When merging, prefer **Squash and merge** for single-commit PRs and **Merge + commit** for multi-commit work where history is meaningful. Avoid **Rebase and + merge** unless the branch is perfectly clean — it rewrites history and removes + the merge traceability. ### Releases - Announce releases in the Council channel when they go out - Tag the release commit with `vX.Y.Z` — this triggers the release workflow -- The GitHub Release notes are auto-generated; add a brief human summary at the top if the automated notes are too sparse +- The GitHub Release notes are auto-generated; add a brief human summary at the + top if the automated notes are too sparse + +### If you are the Steward + +As Steward, you have additional responsibilities beyond what this checklist +covers. The key differences from co-maintainer onboarding: + +- **You drive the revival playbook.** Open a tracking issue in the `.github` + repo immediately after transfer — that issue is the source of truth for the + revival's progress. See [revival-playbook.md][revival-playbook] for the full + checklist. +- **You are the project's tiebreaker.** Contested technical and process + decisions within the repo are yours to resolve, with input from the project's + maintainers. +- **You are the project's external face.** You announce releases, respond to + high-visibility issues, and represent the project when needed. +- **You propose graduation.** When the project meets the criteria in + GOVERNANCE.md, you open the graduation discussion in the Council channel. +- **You flag problems early.** If you are overextended, need to step down, or + believe the project should be archived, notify the Org Admin before the + situation becomes a crisis. Your departure triggers a 30-day vacancy window — + earlier notice means a smoother handoff. + +PSGallery API key issuance is an Org Admin action regardless of your Steward +status — you do not need to create or manage the key directly. + +--- ### Escalation -- Blocked by a technical question? Post in the Council channel — another maintainer may know the answer. -- Blocked by a process question? Ask the Steward. -- Seeing behavior that might violate the Code of Conduct? Report to `conduct@powershellorg.example` or message the Steward directly. -- Need to step down or take a break? Tell the Steward as early as possible — we would rather hand off gracefully than have a repo go dark unexpectedly. +- Blocked by a technical question? Post in the Council channel — another + maintainer may know the answer. +- Blocked by a process question? Ask your project's Steward (or the Org Admin if + you are the Steward). +- Seeing behavior that might violate the Code of Conduct? Report to + or message the Org Admin directly. +- Need to step down or take a break? Tell your project's Steward (or the Org + Admin if you are the Steward) as early as possible — we would rather hand off + gracefully than have a repo go dark unexpectedly. + +[docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication]: + https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication +[PowerShell Gallery]: https://www.powershellgallery.com/ +[revival-playbook]: revival-playbook.md diff --git a/docs/revival-playbook.md b/docs/revival-playbook.md index 74a157f..4b48b9f 100644 --- a/docs/revival-playbook.md +++ b/docs/revival-playbook.md @@ -1,29 +1,39 @@ # Revival Playbook -This playbook describes how to bring an adopted tool from freshly transferred (`status-incoming`) to actively maintained (`status-active`). It is organized into five phases with explicit checklists. +This playbook describes how to bring an adopted tool from freshly transferred +(`status-incoming`) to actively maintained (`status-active`). It is organized +into five phases with explicit checklists. -The phases overlap. Do not wait for Phase 1 to be fully complete before starting Phase 2. The timelines are guidelines; pace to the actual state of the repo. +The phases overlap. Do not wait for Phase 1 to be fully complete before starting +Phase 2. The timelines are guidelines; pace to the actual state of the repo. --- ## Phase 0: Take inventory (week 1) -Everything in this phase happens before or immediately after the repo transfer. It is primarily Steward and lead maintainer work. +Everything in this phase happens before or immediately after the repo transfer. +The project's Steward is confirmed at adoption and owns this phase from day one +— open a tracking issue in the `.github` repo immediately after transfer and use +it as the source of truth for the revival's progress. The Org Admin handles +PSGallery setup; everything else is Steward-driven. ### Transfer and access - [ ] Repo transferred to `github.com/PowerShellOrg` - [ ] Repo topic `status-incoming` applied - [ ] Lead maintainer(s) added to the repo with **Write** access -- [ ] Branch protection rules verified (see [maintainer-onboarding.md](maintainer-onboarding.md)) +- [ ] Branch protection rules verified (see + [maintainer-onboarding.md][maintainer-onboarding]) - [ ] Default branch confirmed as `main` (rename from `master` if needed) ### PSGallery setup -- [ ] PSGallery package ownership transferred to the PowerShellOrg PSGallery account (or new package created if publishing fresh) -- [ ] Scoped API key created by Steward: `PowerShellOrg--`, glob = module name, 365-day expiry +- [ ] PSGallery package ownership transferred to the PowerShellOrg PSGallery + account (or new package created if publishing fresh) +- [ ] Scoped API key created by the Org Admin or a Council member: + `PowerShellOrg--`, glob = module name, 365-day expiry - [ ] `PSGALLERY_API_KEY` Actions secret set in the repo -- [ ] Rotation reminder added to the Steward's private tracking issue +- [ ] Rotation reminder added to the Org Admin's private tracking issue ### Baseline metrics (capture before making changes) @@ -35,29 +45,32 @@ Everything in this phase happens before or immediately after the repo transfer. - [ ] PSGallery download count recorded - [ ] Existing CI status noted (passing / failing / none) -These numbers are the baseline for the first release announcement and are useful for gauging improvement. +These numbers are the baseline for the first release announcement and are useful +for gauging improvement. --- -## Phase 1: Issue triage (weeks 1–4) +## Phase 1: Issue triage (weeks 1-4) -Goal: every open issue is labeled, acknowledged, and either closed or has a clear next step. +Goal: every open issue is labeled, acknowledged, and either closed or has a +clear next step. ### Label framework -Apply the org standard label set if it is not already present. Minimum required labels: - -| Label | Purpose | -|---|---| -| `bug` | Confirmed incorrect behavior | -| `enhancement` | Feature request or improvement | -| `needs-triage` | Newly opened; not yet evaluated | -| `needs-info` | Waiting on reporter for more detail | -| `wontfix` | Valid but outside scope or priority | -| `duplicate` | Duplicate of another issue | -| `good first issue` | Suitable for a new contributor | -| `help wanted` | Maintainer welcomes a PR | -| `question` | How-to or usage question | +Apply the org standard label set if it is not already present. Minimum required +labels: + +| Label | Purpose | +| ------------------ | -------------------------------------- | +| `bug` | Confirmed incorrect behavior | +| `enhancement` | Feature request or improvement | +| `needs-triage` | Newly opened; not yet evaluated | +| `needs-info` | Waiting on reporter for more detail | +| `wontfix` | Valid but outside scope or priority | +| `duplicate` | Duplicate of another issue | +| `good first issue` | Suitable for a new contributor | +| `help wanted` | Maintainer welcomes a PR | +| `question` | How-to or usage question | | `adoption-request` | Tool adoption request (org-level only) | ### Triage process @@ -72,6 +85,7 @@ For each open issue: #### Comment templates **Needs more info:** + ``` Thanks for the report. To help us investigate, could you provide: - [ ] PowerShell version (`$PSVersionTable`) @@ -79,58 +93,78 @@ Thanks for the report. To help us investigate, could you provide: - [ ] Minimal reproduction script - [ ] Full error output -We'll hold this open for 30 days. If we don't hear back, we'll close it — feel free to reopen if you have the info later. +We'll hold this open for 30 days. If we don't hear back, we'll close it — feel +free to reopen if you have the info later. ``` **Closing as won't fix:** -``` -Thank you for taking the time to file this. After review, we've decided not to implement this because [reason]. -If you'd like to discuss further, please open a GitHub Discussion. We're happy to reconsider if the use case evolves. +```markdown +Thank you for taking the time to file this. After review, we've decided not to +implement this because [reason]. + +If you'd like to discuss further, please open a GitHub Discussion. We're happy +to reconsider if the use case evolves. ``` **Closing stale issue (pre-adoption backlog):** -``` -This issue was open before PowerShellOrg adopted this module. We're doing a triage pass to start fresh. -If this is still relevant and reproducible on the latest version, please reopen with a current repro. Thanks for your patience during the transition. +```markdown +This issue was open before PowerShellOrg adopted this module. We're doing a +triage pass to start fresh. + +If this is still relevant and reproducible on the latest version, please reopen +with a current repro. Thanks for your patience during the transition. ``` ### Phase 1 exit criteria - [ ] All open issues have at least one label - [ ] `needs-triage` label is empty -- [ ] Issues older than 2 years with no recent activity are closed with the stale comment above +- [ ] Issues older than 2 years with no recent activity are closed with the + stale comment above --- -## Phase 2: PR triage (weeks 1–4, parallel with Phase 1) +## Phase 2: PR triage (weeks 1-4, parallel with Phase 1) -Goal: no PR sits without a decision. Move every open PR to one of: merged, closed, or actively under review. +Goal: no PR sits without a decision. Move every open PR to one of: merged, +closed, or actively under review. ### Decision tree For each open PR: -1. **Does it still apply cleanly?** If not, ask the author to rebase. If no response in 14 days, close with note. +1. **Does it still apply cleanly?** If not, ask the author to rebase. If no + response in 14 days, close with note. 2. **Is it in scope?** If not, close with explanation. 3. **Does it have tests?** If adding behavior without tests, request them. 4. **Can you merge it as-is?** Merge it. -5. **Can you merge it with minor changes?** Request changes or take over the branch. -6. **Is the author unresponsive?** Close with a note explaining they can reopen when available. +5. **Can you merge it with minor changes?** Request changes or take over the + branch. +6. **Is the author unresponsive?** Close with a note explaining they can reopen + when available. -#### Comment template — taking over a PR: -``` -Thanks for this contribution — the direction is right. Since [this PR has been open for X months / the author is unresponsive / the branch needs a rebase], I'm going to close this and open a new PR that incorporates your approach. +#### Comment template — taking over a PR -Your contribution will be credited in the commit message and CHANGELOG. Thank you for the starting point. -``` +```markdown +Thanks for this contribution — the direction is right. Since [this PR has been +open for X months / the author is unresponsive / the branch needs a rebase], I'm +going to close this and open a new PR that incorporates your approach. -#### Comment template — closing pre-adoption PR: +Your contribution will be credited in the commit message and CHANGELOG. Thank +you for the starting point. ``` -This PR was open before PowerShellOrg adopted this module. As part of our triage, we're closing it to start fresh. -If you'd still like to contribute this change, please open a new PR against the current `main`. See CONTRIBUTING.md for our current guidelines. Thank you for the work you put into this. +#### Comment template — closing pre-adoption PR + +```markdown +This PR was open before PowerShellOrg adopted this module. As part of our +triage, we're closing it to start fresh. + +If you'd still like to contribute this change, please open a new PR against the +current `main`. See CONTRIBUTING.md for our current guidelines. Thank you for +the work you put into this. ``` ### Phase 2 exit criteria @@ -140,7 +174,7 @@ If you'd still like to contribute this change, please open a new PR against the --- -## Phase 3: Build modernization (weeks 2–6) +## Phase 3: Build modernization (weeks 2-6) Goal: the repo builds with the standard stack, CI is green on all platforms. @@ -149,18 +183,21 @@ Work through these in order. Each step is a standalone PR. ### 3a: Pester migration - [ ] Confirm existing tests use Pester (or add tests if none exist) -- [ ] Upgrade to Pester 5 if on an older version — see the [Pester 5 migration guide](https://pester.dev/docs/migrations/v4-to-v5) +- [ ] Upgrade to Pester 5 if on an older version — see the [Pester 5 migration + guide][pester-v5-migration] - [ ] All tests pass locally with `Invoke-Pester` ### 3b: psake bootstrap -- [ ] Add `psakeFile.ps1` to the repo root with the standard tasks: `Init`, `Clean`, `Build`, `Test`, `Analyze`, `Publish` +- [ ] Add `psakeFile.ps1` to the repo root with the standard tasks: `Init`, + `Clean`, `Build`, `Test`, `Analyze`, `Publish` - [ ] `Invoke-psake ?` lists all tasks - [ ] `Invoke-psake Test` runs Pester and passes ### 3c: PowerShellBuild integration -- [ ] `build.ps1` or the `psakeFile.ps1` references PowerShellBuild for shared task logic +- [ ] `build.ps1` or the `psakeFile.ps1` references PowerShellBuild for shared + task logic - [ ] Module manifest is valid (`Test-ModuleManifest` passes) - [ ] `Invoke-psake Build` produces a clean staged module in `output/` @@ -168,11 +205,14 @@ Work through these in order. Each step is a standalone PR. - [ ] `Invoke-psake Analyze` runs PSScriptAnalyzer with the org default ruleset - [ ] All warnings resolved or suppressed with documented justification -- [ ] No `SuppressMessage` attributes without a comment explaining the suppression +- [ ] No `SuppressMessage` attributes without a comment explaining the + suppression ### 3e: GitHub Actions CI -- [ ] `.github/workflows/ci.yml` added to the repo, calling the reusable workflow: +- [ ] `.github/workflows/ci.yml` added to the repo, calling the reusable + workflow: + ```yaml name: CI on: @@ -184,17 +224,20 @@ Work through these in order. Each step is a standalone PR. ci: uses: PowerShellOrg/.github/.github/workflows/powershell-ci.yml@main ``` -- [ ] CI is green on `main` across all four matrix legs (Win/PS5.1, Win/PS7, Linux/PS7, macOS/PS7) + +- [ ] CI is green on `main` across all four matrix legs (Win/PS5.1, Win/PS7, + Linux/PS7, macOS/PS7) - [ ] Branch protection status check updated to require this CI workflow ### 3f: GitHub Actions release workflow - [ ] `.github/workflows/release.yml` added, calling the reusable workflow: + ```yaml name: Release on: push: - tags: ['v*'] + tags: ["v*"] jobs: release: uses: PowerShellOrg/.github/.github/workflows/powershell-release.yml@main @@ -203,11 +246,14 @@ Work through these in order. Each step is a standalone PR. secrets: PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }} ``` -- [ ] Test release with a pre-release tag (e.g., `v1.0.0-beta.1`) to confirm the workflow runs end-to-end + +- [ ] Test release with a pre-release tag (e.g., `v1.0.0-beta.1`) to confirm the + workflow runs end-to-end ### 3g: Test coverage baseline -- [ ] Coverage report generated (Pester's `-CodeCoverage` parameter or a coverage tool) +- [ ] Coverage report generated (Pester's `-CodeCoverage` parameter or a + coverage tool) - [ ] Baseline coverage percentage recorded in the tracking issue - [ ] At least critical public functions have tests; gaps documented as issues @@ -220,20 +266,28 @@ Work through these in order. Each step is a standalone PR. --- -## Phase 4: First clean release (weeks 4–8) +## Phase 4: First clean release (weeks 4-8) -Goal: cut a release under the PowerShellOrg banner that you are proud to put your name on. +Goal: cut a release under the PowerShellOrg banner that you are proud to put +your name on. ### Release gate checklist -- [ ] `CHANGELOG.md` exists and documents what has changed since the last release (even if that is just "Transferred to PowerShellOrg, CI modernized") -- [ ] Module version bumped appropriately (patch if no user-facing changes, minor if new features, major if breaking) +- [ ] `CHANGELOG.md` exists and documents what has changed since the last + release (even if that is just "Transferred to PowerShellOrg, CI + modernized") +- [ ] Module version bumped appropriately (patch if no user-facing changes, + minor if new features, major if breaking) - [ ] All tests passing on CI - [ ] PSScriptAnalyzer clean -- [ ] Module manifest is accurate: description, author (or organization), copyright, tags, PSGallery URLs -- [ ] `README.md` updated: installation instructions current, usage examples work, badges updated -- [ ] Any open critical bugs addressed or explicitly deferred with a documented reason -- [ ] At least one other maintainer has reviewed the release PR (or Steward if solo) +- [ ] Module manifest is accurate: description, author (or organization), + copyright, tags, PSGallery URLs +- [ ] `README.md` updated: installation instructions current, usage examples + work, badges updated +- [ ] Any open critical bugs addressed or explicitly deferred with a documented + reason +- [ ] At least one other maintainer has reviewed the release PR (or Steward if + solo) ### Release steps @@ -242,7 +296,8 @@ Goal: cut a release under the PowerShellOrg banner that you are proud to put you 3. Get at least one review 4. Merge to `main` 5. Push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z` -6. Confirm the release workflow succeeds: PSGallery package updated, GitHub Release created +6. Confirm the release workflow succeeds: PSGallery package updated, GitHub + Release created 7. Announce in the Council channel ### Phase 4 exit criteria @@ -255,25 +310,33 @@ Goal: cut a release under the PowerShellOrg banner that you are proud to put you ## Phase 5: Ongoing maintenance and transition to active -Once Phase 4 is done, the repo transitions from `status-incoming` to `status-active`. +Once Phase 4 is done, the repo transitions from `status-incoming` to +`status-active`. ### Transition checklist - [ ] Repo topic updated from `status-incoming` to `status-active` - [ ] `README.md` status badge updated -- [ ] Steward notified (they will update any org-level tracking) +- [ ] Org Admin notified (they will update any org-level tracking) - [ ] Announcement posted in Council channel ### Ongoing cadence -| Activity | Frequency | -|---|---| -| Issue triage | Weekly (or within 7 days of new issues) | -| PR review | Within 7 days of opening | -| Dependency review | Monthly (check for PSGallery module updates) | -| Release | As needed; no more than 3 months between releases if there are merged changes | -| PSGallery API key rotation | Annually (Steward-driven, maintainer confirms) | +| Activity | Frequency | +| -------------------------- | ----------------------------------------------------------------------------- | +| Issue triage | Weekly (or within 7 days of new issues) | +| PR review | Within 7 days of opening | +| Dependency review | Monthly (check for PSGallery module updates) | +| Release | As needed; no more than 3 months between releases if there are merged changes | +| PSGallery API key rotation | Annually (Org Admin-driven, Steward confirms) | ### Graduation to stable -When the repo has been in `status-active` for at least 12 months, has had 2+ clean releases, has 2+ active maintainers, and has no critical open issues, propose graduation to `status-stable` in the Council channel. See [GOVERNANCE.md](../.github/GOVERNANCE.md) for the graduation criteria. +When the repo has been in `status-active` for at least 12 months, has had 2+ +clean releases, has 2+ active maintainers, and has no critical open issues, +propose graduation to `status-stable` in the Council channel. See +[GOVERNANCE.md][governance] for the graduation criteria. + +[maintainer-onboarding]: maintainer-onboarding.md +[pester-v5-migration]: https://pester.dev/docs/migrations/v4-to-v5 +[governance]: ../.github/GOVERNANCE.md diff --git a/profile/README.md b/profile/README.md index dbb5532..15a7fe4 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,19 +1,26 @@ # PowerShellOrg -PowerShellOrg is a community-run GitHub organization that adopts and maintains open-source PowerShell tools that would otherwise go unmaintained. +PowerShellOrg is a community-run GitHub organization that adopts and maintains +open-source PowerShell tools that would otherwise go unmaintained. ## Maintained tools -| Module | Description | Status | -|---|---|---| -| [Plaster](https://github.com/PowerShellOrg/Plaster) | Template-based scaffolding engine for PowerShell projects and modules | ![Active](https://img.shields.io/badge/status-active-brightgreen) | -| [PSDepend](https://github.com/PowerShellOrg/PSDepend) | Dependency management for PowerShell scripts and modules | ![Active](https://img.shields.io/badge/status-active-brightgreen) | +| Module | Description | Status | Steward | +| -------------------- | --------------------------------------------------------------------- | ------------------------ | --------------- | +| [Plaster][plaster] | Template-based scaffolding engine for PowerShell projects and modules | ![Active][status-active] | James Petty | +| [PSDepend][psdepend] | Dependency management for PowerShell scripts and modules | ![Active][status-active] | Gilbert Sanchez | + +**Status legend:** ![Active][status-active] actively maintained · ![Stable][status-stable] stable, reduced cadence · ![Paused][status-paused] Steward vacancy in progress · ![Archived][status-archived] read-only ## Want us to adopt your tool? -If you maintain (or used to maintain) a PowerShell tool that needs a new home, we want to hear from you. +If you maintain (or used to maintain) a PowerShell tool that needs a new home, +we want to hear from you. -Read the [adoption criteria](https://github.com/PowerShellOrg/.github/blob/main/docs/adoption-criteria.md) first, then open an **[Adoption Request](https://github.com/PowerShellOrg/.github/issues/new?template=tool_adoption_request.yml)**. +Every adoption requires a committed **Steward** — someone who will own the +project's direction and drive the revival. Read the [adoption +criteria][adoption-criteria] to understand what that means, then open an +**[Adoption Request][adoption-request]**. We respond to all requests within 7 days and make a decision within 30. @@ -21,12 +28,36 @@ We respond to all requests within 7 days and make a decision within 30. Every project in this org accepts contributions. A good place to start: -- **[Good first issues across the org](https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3APowerShellOrg+label%3A%22good+first+issue%22)** — smaller, well-scoped tasks -- **[Help wanted across the org](https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3APowerShellOrg+label%3A%22help+wanted%22)** — tasks where we've explicitly asked for a PR +- **[Good first issues across the org][good-first-issues]** — smaller, + well-scoped tasks +- **[Help wanted across the org][help-wanted]** — tasks where we've explicitly + asked for a PR -See [CONTRIBUTING.md](https://github.com/PowerShellOrg/.github/blob/main/.github/CONTRIBUTING.md) for how we work. +See [CONTRIBUTING.md][contributing] for how we work. ## Governance and community -- [Governance model](https://github.com/PowerShellOrg/.github/blob/main/.github/GOVERNANCE.md) — how decisions get made, roles, maintainer lifecycle -- [Code of Conduct](https://github.com/PowerShellOrg/.github/blob/main/.github/CODE_OF_CONDUCT.md) — how we treat each other +- [Governance model][governance] — how decisions get made, roles, maintainer + lifecycle +- [Code of Conduct][code-of-conduct] — how we treat each other + +[plaster]: https://github.com/PowerShellOrg/Plaster +[psdepend]: https://github.com/PowerShellOrg/PSDepend +[status-active]: https://img.shields.io/badge/status-active-brightgreen +[status-stable]: https://img.shields.io/badge/status-stable-blue +[status-paused]: https://img.shields.io/badge/status-paused-yellow +[status-archived]: https://img.shields.io/badge/status-archived-lightgrey +[adoption-criteria]: + https://github.com/PowerShellOrg/.github/blob/main/docs/adoption-criteria.md +[adoption-request]: + https://github.com/PowerShellOrg/.github/issues/new?template=tool_adoption_request.yml +[good-first-issues]: + https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3APowerShellOrg+label%3A%22good+first+issue%22 +[help-wanted]: + https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3APowerShellOrg+label%3A%22help+wanted%22 +[contributing]: + https://github.com/PowerShellOrg/.github/blob/main/.github/CONTRIBUTING.md +[governance]: + https://github.com/PowerShellOrg/.github/blob/main/.github/GOVERNANCE.md +[code-of-conduct]: + https://github.com/PowerShellOrg/.github/blob/main/.github/CODE_OF_CONDUCT.md