Skip to content

Commit 4cde3ba

Browse files
HeyItsGilbertHeyItsGilbert
authored
Merge pull request #8 from PowerShellOrg/pr/06-docs
chore: merge complete PR stack into main
2 parents b1dc2d9 + 7fdeb90 commit 4cde3ba

21 files changed

Lines changed: 1913 additions & 0 deletions

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# PowerShellOrg Code of Conduct
2+
3+
PowerShellOrg has adopted the Contributor Covenant version 3.0 as our Code of
4+
Conduct. The full text follows, with PowerShellOrg-specific reporting and
5+
enforcement details filled in.
6+
7+
## Our Pledge
8+
9+
We as members, contributors, leaders, and participants in the PowerShellOrg
10+
community pledge to make participation in our community a harassment-free
11+
experience for everyone, regardless of age, body size, visible or invisible
12+
disability, ethnicity, sex characteristics, gender identity and expression,
13+
level of experience, education, socio-economic status, nationality, personal
14+
appearance, race, caste, color, religion, sexual identity and orientation, or
15+
any other dimension of diversity.
16+
17+
We pledge to act and interact in ways that contribute to an open, welcoming,
18+
diverse, inclusive, and healthy community, focused on the shared goal of
19+
building and maintaining open source PowerShell tooling.
20+
21+
## Encouraged Behaviors
22+
23+
We encourage all community members to:
24+
25+
- Demonstrate empathy, kindness, and respect toward other people
26+
- Be respectful of differing opinions, viewpoints, and experiences
27+
- Give and gracefully accept constructive feedback
28+
- Accept responsibility, apologize to those affected by our mistakes, and learn
29+
from the experience
30+
- Focus on what is best not just for us as individuals, but for the overall
31+
community
32+
- Use welcoming and inclusive language
33+
- Help newcomers feel welcome and supported
34+
- Credit others' contributions generously
35+
36+
## Unacceptable Behaviors
37+
38+
The following behaviors are considered violations of this Code of Conduct:
39+
40+
- Harassment of any participant, in any form
41+
- Discrimination, particularly against members of vulnerable or underrepresented
42+
groups
43+
- The use of sexualized language or imagery, and sexual attention or advances of
44+
any kind
45+
- Trolling, insulting or derogatory comments, and personal or political attacks
46+
- Public or private harassment, including stalking, doxxing, or sustained
47+
disruption of discussions
48+
- Publishing others' private information, such as a physical or email address,
49+
without their explicit permission
50+
- Advocating for, or encouraging, any of the above behavior
51+
- Other conduct which could reasonably be considered inappropriate in a
52+
professional setting
53+
54+
We recognize that even well-intentioned actions can cause harm. Impact matters
55+
more than intent. When informed that our behavior has caused harm, the
56+
appropriate response is to listen, take responsibility, apologize sincerely, and
57+
change the behavior — not to defend the original intent.
58+
59+
## Consent and Boundaries
60+
61+
Community members must respect stated boundaries immediately. When a member asks
62+
another to stop a behavior, end a line of conversation, or leave them alone, the
63+
request must be honored without argument.
64+
65+
Repeated boundary violations after a clear request to stop will be treated as
66+
harassment.
67+
68+
## Scope
69+
70+
This Code of Conduct applies within all PowerShellOrg community spaces,
71+
including:
72+
73+
- All repositories within github.com/PowerShellOrg
74+
- GitHub Discussions, Issues, and Pull Requests
75+
- Any official PowerShellOrg communication channels (chat platforms, mailing
76+
lists, video calls)
77+
- Public events where someone is officially representing PowerShellOrg
78+
79+
It also applies when an individual is officially representing the community in
80+
public spaces. Examples of representing our community include using an official
81+
email address, posting via an official social media account, or acting as an
82+
appointed representative at an online or offline event.
83+
84+
This Code of Conduct also applies to behavior outside these spaces when that
85+
behavior has the potential to adversely affect the safety and well-being of
86+
community members.
87+
88+
## Reporting Concerns
89+
90+
If you experience or witness behavior that violates this Code of Conduct, please
91+
report it. You will not be retaliated against for making a good-faith report.
92+
93+
**Primary contact:** <Privacy@powershell.org>
94+
95+
**Alternate contact:** Direct message to the Steward via GitHub or Discord.
96+
97+
When reporting, please include:
98+
99+
- Your contact information (so we can follow up)
100+
- Names (real or usernames) of any individuals involved, including witnesses
101+
- A description of what happened, with as much specificity as possible
102+
- The approximate date and time
103+
- Links to any relevant public records (issues, pull requests, chat messages)
104+
- Any additional context that would help us understand the situation
105+
- Whether you believe the situation is ongoing
106+
107+
Reports will be acknowledged within 72 hours.
108+
109+
All reports will be handled with discretion. We will not share your identity
110+
with the person you are reporting without your explicit consent, except where
111+
required by law.
112+
113+
## Addressing and Repairing Harm
114+
115+
When a Code of Conduct violation is reported, the Steward (with input from the
116+
Council where appropriate) will determine an appropriate response. Our goal is
117+
to address harm, support those affected, and where possible find a path for the
118+
person who caused harm to repair the relationship and reintegrate into the
119+
community.
120+
121+
The following is a guideline. The Steward retains discretion to apply responses
122+
appropriate to the specific situation, including responses not listed here.
123+
124+
### 1. Private Conversation
125+
126+
**Community impact:** Use of inappropriate language, a single instance of
127+
unprofessional behavior, or behavior that, while not severe, was unwelcome.
128+
129+
**Response:** A private written communication from the Steward, providing
130+
clarity around the nature of the violation and an explanation of why the
131+
behavior was inappropriate. A public apology may be requested.
132+
133+
### 2. Warning
134+
135+
**Community impact:** A violation through a single incident or series of
136+
actions, or a pattern of behavior that has caused harm to one or more community
137+
members.
138+
139+
**Response:** A written warning with consequences for continued behavior. No
140+
interaction with the people involved, including unsolicited interaction with
141+
those enforcing the Code of Conduct, for a specified period of time. This
142+
includes avoiding interactions in community spaces as well as external channels
143+
like social media. Violating these terms may lead to a temporary or permanent
144+
ban.
145+
146+
### 3. Temporary Ban
147+
148+
**Community impact:** A serious violation of community standards, including
149+
sustained inappropriate behavior or harassment of an individual.
150+
151+
**Response:** A temporary ban from any sort of interaction or public
152+
communication with the community for a specified period of time. No public or
153+
private interaction with the people involved, including unsolicited interaction
154+
with those enforcing the Code of Conduct, is allowed during this period.
155+
Violating these terms may lead to a permanent ban.
156+
157+
### 4. Permanent Ban
158+
159+
**Community impact:** Demonstrating a pattern of violation of community
160+
standards, including sustained inappropriate behavior, harassment of an
161+
individual, or aggression toward or disparagement of classes of individuals.
162+
163+
**Response:** A permanent ban from any sort of public interaction within the
164+
community.
165+
166+
## Restorative Paths
167+
168+
Where appropriate, and at the discretion of the Steward and the affected
169+
parties, we may offer paths for community members who have caused harm to repair
170+
the relationship and re-engage with the community. This may include:
171+
172+
- A private acknowledgment of the harm caused
173+
- A public apology, when requested by those harmed
174+
- A defined period of restricted participation
175+
- A clear set of expectations for re-engagement
176+
177+
Restorative paths are not available for severe violations, including but not
178+
limited to harassment, doxxing, threats of violence, or sexual misconduct.
179+
180+
## Appeals
181+
182+
A person who has been subject to enforcement action may appeal the decision by
183+
writing to the Steward within 30 days. The Steward will review the appeal with
184+
input from the Council and respond within 30 days.
185+
186+
If the appeal involves the Steward's own decision and the appellant believes the
187+
Steward cannot review it impartially, they may request that the Council review
188+
the appeal collectively. In that case, the Council reviews and decides by
189+
majority, and the Steward does not vote.
190+
191+
## Attribution
192+
193+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
194+
version 3.0, available at
195+
<https://www.contributor-covenant.org/version/3/0/code_of_conduct/>.
196+
197+
[homepage]: https://www.contributor-covenant.org
198+
199+
For answers to common questions about this Code of Conduct, see the FAQ at
200+
<https://www.contributor-covenant.org/faq>. Translations are available at
201+
<https://www.contributor-covenant.org/translations>.
202+
203+
---
204+
205+
*Last updated: 2026/04/21. Reports go to <Privacy@powershell.org>.*

‎.github/CONTRIBUTING.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to PowerShellOrg Projects
2+
3+
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.
4+
5+
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.
6+
7+
---
8+
9+
## Scope and governance
10+
11+
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.
12+
13+
---
14+
15+
## Before you contribute
16+
17+
1. **Check existing issues and PRs.** Someone may already be working on it.
18+
2. **Read the repo's README.** Each project documents its purpose, status, and any project-specific constraints.
19+
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.
20+
21+
---
22+
23+
## Development setup
24+
25+
All PowerShellOrg projects use the same build stack:
26+
27+
| Tool | Purpose |
28+
|---|---|
29+
| [psake](https://github.com/psake/psake) | Build automation |
30+
| [PowerShellBuild](https://github.com/psake/PowerShellBuild) | Shared psake task library |
31+
| [Pester 5](https://pester.dev) | Testing |
32+
| [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) | Static analysis |
33+
34+
**Install build dependencies:**
35+
36+
```powershell
37+
Install-Module psake -Scope CurrentUser -Force
38+
Install-Module PowerShellBuild -Scope CurrentUser -Force
39+
Install-Module Pester -Scope CurrentUser -Force -MinimumVersion '5.0'
40+
Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
41+
```
42+
43+
**Common psake tasks** (every repo exposes these):
44+
45+
```powershell
46+
Invoke-psake Init # First-time setup
47+
Invoke-psake Clean # Remove build artifacts
48+
Invoke-psake Build # Compile / stage the module
49+
Invoke-psake Test # Run Pester tests
50+
Invoke-psake Analyze # Run PSScriptAnalyzer
51+
Invoke-psake Publish # Publish to PSGallery (maintainers only)
52+
```
53+
54+
Run `Invoke-psake ?` to see all available tasks and their descriptions.
55+
56+
**Target platforms:** Windows PowerShell 5.1 and PowerShell 7.x on Windows, Linux, and macOS. Write code that runs on all six combinations.
57+
58+
---
59+
60+
## Branching and commits
61+
62+
- **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`.
63+
- **Keep commits focused.** One logical change per commit. Use the [Conventional Commits](https://www.conventionalcommits.org/) style:
64+
- `fix: correct null reference in Invoke-PSDepend`
65+
- `feat: add -WhatIf support to Install task`
66+
- `docs: clarify quickstart example`
67+
- `chore: bump Pester to 5.6`
68+
- `test: add coverage for empty dependency file`
69+
- **Do not squash history prematurely.** Maintainers may squash on merge if appropriate.
70+
- **Keep `main` green.** Never force-push to `main` or shared branches.
71+
72+
---
73+
74+
## Pull request expectations
75+
76+
Before opening a PR:
77+
78+
- [ ] `Invoke-psake Test` passes locally on at least one platform
79+
- [ ] `Invoke-psake Analyze` passes with no new warnings
80+
- [ ] New behavior has Pester test coverage
81+
- [ ] `CHANGELOG.md` is updated for user-facing changes
82+
- [ ] Docs are updated if behavior changed
83+
84+
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.
85+
86+
**Draft PRs** are welcome for early feedback. Mark them ready for review when you want the full review pass.
87+
88+
---
89+
90+
## Code review expectations
91+
92+
### For contributors
93+
94+
- Respond to review comments within **14 days**. If you need more time, say so — we will wait.
95+
- If a comment is a question, answer it. If it is a request, either make the change or explain why you disagree.
96+
- A maintainer will make the final call. Disagreements are discussed, not escalated.
97+
98+
### For maintainers
99+
100+
| Repo status | First response SLA | Review completion SLA |
101+
|---|---|---|
102+
| `status-active` | 7 days | 30 days |
103+
| `status-stable` | 30 days | 60 days |
104+
105+
SLAs are best-effort commitments, not guarantees. If a repo is understaffed, the Steward will note this in the repo's README.
106+
107+
If a PR sits without response past the SLA, ping `@PowerShellOrg/maintainers` or open a discussion.
108+
109+
---
110+
111+
## Releases
112+
113+
Releases are cut by maintainers. The process:
114+
115+
1. Maintainer updates `CHANGELOG.md` and bumps the module version in the manifest.
116+
2. Maintainer opens a PR titled `chore: release vX.Y.Z`.
117+
3. PR is reviewed and merged to `main`.
118+
4. Maintainer pushes a version tag (`vX.Y.Z`) to `main`.
119+
5. The tag triggers `powershell-release.yml`, which builds, publishes to PSGallery, and creates a GitHub Release.
120+
121+
Contributors do not cut releases. If you believe a release is overdue, open an issue and tag the maintainers.
122+
123+
---
124+
125+
## License by contribution
126+
127+
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.
128+
129+
If your employer has rights to code you write, ensure you have permission to contribute it before submitting.
130+
131+
---
132+
133+
## Questions?
134+
135+
See [SUPPORT.md](SUPPORT.md).

‎.github/DISCUSSION_TEMPLATE/announcements.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
title: "[Announcement]: "
2+
labels:
3+
- announcement
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Use this template for official announcements: new releases, adoption news, governance changes, maintainer changes, or other org-wide updates.
9+
10+
Only maintainers and the Steward should post in this category. Community members can react and reply.
11+
12+
- type: textarea
13+
id: announcement
14+
attributes:
15+
label: Announcement
16+
description: The full announcement text. Include links to relevant issues, PRs, or releases.
17+
validations:
18+
required: true

‎.github/DISCUSSION_TEMPLATE/general.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
title: ""
2+
labels: []
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
This is the place for general conversation about PowerShellOrg and its projects.
8+
9+
For bug reports, use [Issues](../../issues/new/choose). For feature requests, use [Issues](../../issues/new/choose). For how-to questions, use the [Q&A category](../../discussions/new?category=q-a).
10+
11+
- type: textarea
12+
id: discussion
13+
attributes:
14+
label: What's on your mind?
15+
validations:
16+
required: true

0 commit comments

Comments
 (0)