Skip to content

Commit 82a7bd9

Browse files
psjamesppsjamesp
authored
Merge pull request #6 from PowerShellOrg/pr/06-docs
2 parents 07f55f6 + 7fdeb90 commit 82a7bd9

4 files changed

Lines changed: 564 additions & 0 deletions

File tree

‎docs/adoption-criteria.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Adoption Criteria
2+
3+
This document describes how PowerShellOrg evaluates tools for adoption, what we commit to when we adopt something, and what the submitter commits to.
4+
5+
Read this before submitting a [Tool Adoption Request](https://github.com/PowerShellOrg/.github/issues/new?template=tool_adoption_request.yml).
6+
7+
---
8+
9+
## Must-be-true criteria
10+
11+
All six of the following must be true before we will adopt a tool. These are not negotiable.
12+
13+
### 1. Open-source license
14+
15+
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.
16+
17+
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.
18+
19+
### 2. Author consent or demonstrated abandonment
20+
21+
We do not take over maintained projects without permission.
22+
23+
- **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.
24+
- **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.
25+
26+
When in doubt, we wait. Burning bridges with the original author is not worth any single tool.
27+
28+
### 3. Real user base
29+
30+
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.
31+
32+
We will not adopt a tool that has no users outside its author, because there would be no one to maintain it for.
33+
34+
### 4. Manageable scope
35+
36+
The tool's maintenance burden must be sustainable given the org's current maintainer pool. We consider:
37+
38+
- Lines of code and architectural complexity
39+
- Test coverage and CI state (a tool with no tests requires significant upfront investment)
40+
- Open issue and PR backlog
41+
- Dependency footprint
42+
43+
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.
44+
45+
### 5. No unaddressed security issues
46+
47+
We will not inherit a tool with known, unaddressed security vulnerabilities. Before adoption, the submitter must either:
48+
49+
- Confirm there are no known security issues, or
50+
- Document all known issues and commit to addressing them in the first release cycle
51+
52+
This is not about perfection — it is about not knowingly shipping something unsafe to our users.
53+
54+
### 6. No legal encumbrance
55+
56+
The tool must not carry legal risks that would expose PowerShellOrg or its maintainers. Examples of disqualifying encumbrances:
57+
58+
- Copyright claims from a third party
59+
- Code copied from a non-compatible license without attribution
60+
- Trademark issues
61+
- Export control restrictions
62+
63+
---
64+
65+
## What PowerShellOrg commits to
66+
67+
When we adopt a tool, we commit to:
68+
69+
1. **Maintaining it actively** — responding to issues within our SLA, reviewing PRs, and cutting releases when there are meaningful changes
70+
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
71+
3. **Keeping it open source** — the tool will remain under its existing OSI license (or a compatible one with explicit permission)
72+
4. **Not breaking the API or CLI interface without a major version bump** — we respect existing users' scripts and pipelines
73+
5. **Giving credit** — the original author's contributions remain in git history and are acknowledged in the CHANGELOG and package metadata
74+
6. **Handling security responsibly** — following our published security policy for vulnerability disclosure and response
75+
76+
---
77+
78+
## What the submitter commits to
79+
80+
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.
81+
82+
If you are submitting a request and are willing to maintain the tool:
83+
84+
1. **Minimum 6 months of active maintenance** — you will triage issues, review PRs, and be reachable for at least 6 months after adoption
85+
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
86+
3. **Good-faith participation** — you will engage with the community, respond to review comments, and follow PowerShellOrg's contribution norms
87+
4. **Transparency about limitations** — if you know the tool has problems, you will document them upfront rather than letting us discover them post-adoption
88+
89+
We understand life happens. If you need to step back before the 6 months are up, tell us early — we will work with you.
90+
91+
---
92+
93+
## The adoption workflow
94+
95+
| Step | Owner | Timeline |
96+
|---|---|---|
97+
| Submitter files a Tool Adoption Request | Submitter | — |
98+
| Steward acknowledges the request and assigns it to the Council | Steward | 7 days |
99+
| Council members review and comment | Council | 30 days |
100+
| Steward makes a decision (adopt / decline / defer) | Steward | 30 days from submission |
101+
| If adopted: repo transfer initiated, onboarding begins | Steward + submitter | Week of decision |
102+
| Repo moves to `status-incoming`, Revival Playbook begins | Lead maintainer | Immediately after transfer |
103+
104+
### What "declined" means
105+
106+
A declined adoption request is not a judgment on the tool's quality or the submitter's intentions. Common reasons for declining:
107+
108+
- The tool does not meet one of the must-be-true criteria
109+
- Our current maintainer pool cannot take it on right now
110+
- A better maintainer or org has already stepped up
111+
112+
We will always explain the reason. Declined requests may be resubmitted when circumstances change.
113+
114+
### What "deferred" means
115+
116+
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.

‎docs/maintainer-onboarding.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Maintainer Onboarding
2+
3+
Welcome to PowerShellOrg. This checklist walks you through everything you need to be fully operational on day one and productive in the first week.
4+
5+
---
6+
7+
## Day 1: Access and accounts
8+
9+
### GitHub org access
10+
11+
- [ ] Accept the org invite from the Steward (check your GitHub notifications and email)
12+
- [ ] Verify you have **Write** access to your assigned repo(s) — navigate to the repo → **Settings** → **Collaborators and teams**
13+
- [ ] 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))
14+
15+
### Council channel
16+
17+
- [ ] Introduce yourself in the Council channel: `<FILL IN: channel URL or invite link>`
18+
- [ ] Note your timezone and typical availability (helps set realistic review expectations)
19+
20+
### PSGallery account
21+
22+
- [ ] Confirm you have a [PowerShell Gallery](https://www.powershellgallery.com/) account
23+
- [ ] Share your PSGallery username with the Steward — you will need it for the API key issuance step below
24+
25+
---
26+
27+
## Day 1: Repo familiarization
28+
29+
- [ ] Clone the repo locally
30+
- [ ] Read the repo's `README.md` and any existing `CONTRIBUTING.md`
31+
- [ ] Read `CHANGELOG.md` to understand recent history
32+
- [ ] Read open issues and PRs — look for anything labeled `needs-triage` or with recent activity
33+
34+
---
35+
36+
## Day 1: Branch protection verification
37+
38+
Verify the repo's default branch has the following protections enabled. Navigate to the repo → **Settings** → **Branches** → branch protection rule for `main`.
39+
40+
- [ ] **Require a pull request before merging** — enabled
41+
- [ ] **Require approvals** — at least 1 required reviewer
42+
- [ ] **Dismiss stale pull request approvals when new commits are pushed** — enabled
43+
- [ ] **Require status checks to pass before merging** — enabled; the CI workflow must be listed
44+
- [ ] **Require branches to be up to date before merging** — enabled
45+
- [ ] **Require linear history** — enabled
46+
- [ ] **Do not allow force pushes** — enabled
47+
- [ ] **Do not allow deletions** — enabled
48+
49+
If any of these are missing, notify the Steward before merging anything.
50+
51+
---
52+
53+
## Day 1: PSGallery API key
54+
55+
PowerShellOrg uses **per-repo scoped API keys** for PSGallery. You do not get an org-wide key.
56+
57+
### Key issuance process (Steward action)
58+
59+
The Steward creates the key with these parameters:
60+
61+
| Parameter | Value |
62+
|---|---|
63+
| Key name | `PowerShellOrg-<RepoName>-<YYYY-MM>` (e.g., `PowerShellOrg-PSDepend-2025-11`) |
64+
| Glob pattern | The module name exactly (e.g., `PSDepend`) |
65+
| Expiration | 365 days (the PSGallery maximum) |
66+
67+
The Steward then:
68+
1. Creates or updates the `PSGALLERY_API_KEY` Actions secret in the repo
69+
2. Adds a rotation reminder to the private key tracking issue (pinned to this repo)
70+
3. Notifies the maintainer that the key is in place
71+
72+
### Maintainer steps
73+
74+
- [ ] Confirm with the Steward that `PSGALLERY_API_KEY` is set in the repo's Actions secrets (**Settings** → **Secrets and variables** → **Actions**)
75+
- [ ] Note the key expiration month — the Steward will initiate rotation, but you may be asked to trigger it
76+
77+
### Key rotation
78+
79+
Keys expire after 365 days. The Steward tracks rotation in a private pinned issue. When rotation is due:
80+
1. Steward creates a new key on PSGallery with the same glob, new `YYYY-MM` suffix in the name
81+
2. Steward updates the `PSGALLERY_API_KEY` secret in the repo
82+
3. Old key is deleted from PSGallery
83+
4. Tracking issue is updated
84+
85+
---
86+
87+
## Day 1: CI bootstrap
88+
89+
- [ ] Install the standard build stack locally:
90+
91+
```powershell
92+
Install-Module psake -Scope CurrentUser -Force
93+
Install-Module PowerShellBuild -Scope CurrentUser -Force
94+
Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
95+
Install-Module Pester -Scope CurrentUser -Force -MinimumVersion '5.0' -MaximumVersion '5.99'
96+
```
97+
98+
- [ ] Run `Invoke-psake ?` in the repo root — confirm the standard tasks are listed (Init, Clean, Build, Test, Analyze, Publish)
99+
- [ ] Run `Invoke-psake Test` — confirm all tests pass
100+
- [ ] Run `Invoke-psake Analyze` — confirm no PSScriptAnalyzer warnings
101+
- [ ] Navigate to the repo's **Actions** tab and confirm the CI workflow is running and green on `main`
102+
103+
If the CI workflow is not present or not green, see the [Revival Playbook](revival-playbook.md) Phase 3 for modernization steps.
104+
105+
---
106+
107+
## First week: Communication norms
108+
109+
### Issue and PR triage
110+
111+
| Repo status | First-response target |
112+
|---|---|
113+
| `status-active` | 7 days |
114+
| `status-stable` | 30 days |
115+
116+
First response means: a label applied, a comment acknowledging the issue, or a review comment on the PR — not necessarily a resolution.
117+
118+
Set up GitHub notifications for your repo: **Watch** → **All activity**, or at minimum **Issues** and **Pull requests**.
119+
120+
### Code review
121+
122+
- Aim to complete (not just start) reviews within 30 days of assignment
123+
- Use GitHub's "Request changes" only when a change is genuinely blocking — a comment thread is sufficient for most feedback
124+
- 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.
125+
126+
### Releases
127+
128+
- Announce releases in the Council channel when they go out
129+
- Tag the release commit with `vX.Y.Z` — this triggers the release workflow
130+
- The GitHub Release notes are auto-generated; add a brief human summary at the top if the automated notes are too sparse
131+
132+
### Escalation
133+
134+
- Blocked by a technical question? Post in the Council channel — another maintainer may know the answer.
135+
- Blocked by a process question? Ask the Steward.
136+
- Seeing behavior that might violate the Code of Conduct? Report to `conduct@powershellorg.example` or message the Steward directly.
137+
- 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.

0 commit comments

Comments
 (0)