Skip to content

Commit f2c4d1b

Browse files
stevevillardistevevillardi
committed
Create CONTRIBUTOR_GUIDELINES.md
1 parent 704196f commit f2c4d1b

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎CONTRIBUTOR_GUIDELINES.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Contributor Guidelines for Community PowerShell Module
2+
3+
Thank you for your interest in contributing to our PowerShell module! This document provides guidelines to ensure consistency and quality across all contributions.
4+
5+
## Table of Contents
6+
- [Getting Started](#getting-started)
7+
- [Development Environment Setup](#development-environment-setup)
8+
- [Coding Standards](#coding-standards)
9+
- [Documentation Requirements](#documentation-requirements)
10+
- [Testing Guidelines](#testing-guidelines)
11+
- [Pull Request Process](#pull-request-process)
12+
- [Issue Reporting](#issue-reporting)
13+
- [Community Expectations](#community-expectations)
14+
15+
## Getting Started
16+
17+
1. **Fork the repository** to your GitHub account
18+
2. **Clone your fork** to your local development environment
19+
3. **Create a new branch** for your contribution (use a descriptive name related to your change)
20+
4. Make your changes following our guidelines below
21+
5. Submit a pull request back to the main repository
22+
23+
## Development Environment Setup
24+
25+
### Required Tools
26+
- PowerShell 5.1 or PowerShell Core 7.x
27+
- VS Code with PowerShell extension (recommended)
28+
- Pester 5.x for testing
29+
- PSScriptAnalyzer for linting
30+
31+
### Initial Setup
32+
```powershell
33+
# Install required modules if you don't have them
34+
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force
35+
Install-Module -Name PSScriptAnalyzer -Force
36+
37+
# Clone the repository
38+
git clone https://github.com/YOUR-USERNAME/powershell-module.git
39+
cd powershell-module
40+
41+
# Set up pre-commit hooks (optional but recommended)
42+
./scripts/setup-dev-environment.ps1
43+
```
44+
45+
## Coding Standards
46+
47+
### Naming Conventions
48+
- Use **PascalCase** for function names, parameter names, and variable names
49+
- Use **Approved Verbs** for functions (use `Get-Verb` to see the list)
50+
- Use singular nouns for cmdlet names (e.g., `Get-User` not `Get-Users`)
51+
- Use descriptive names that clearly indicate purpose
52+
53+
### Code Structure
54+
- Each function should be in its own file named after the function
55+
- Group related functions in appropriately named subdirectories
56+
- Use the standard PowerShell module structure
57+
- Place internal/helper functions in a `Private` directory
58+
59+
### Style Guidelines
60+
- Use 4 spaces for indentation (not tabs)
61+
- Follow [PowerShell Best Practices](https://github.com/PoshCode/PowerShellPracticeAndStyle)
62+
- Limit line length to 100 characters where possible
63+
- Include a blank line between logical sections of code
64+
- Always use `{}` for script blocks, even one-liners
65+
66+
```powershell
67+
# Good example
68+
function Get-Example {
69+
[CmdletBinding()]
70+
param (
71+
[Parameter(Mandatory = $true)]
72+
[string]$Name
73+
)
74+
75+
process {
76+
# Function logic here
77+
}
78+
}
79+
```
80+
81+
## Documentation Requirements
82+
83+
### Comment-Based Help
84+
Every function must include comment-based help with:
85+
- Synopsis
86+
- Description
87+
- At least one example
88+
- All parameters documented
89+
- Any outputs described
90+
91+
Example:
92+
```powershell
93+
<#
94+
.SYNOPSIS
95+
Retrieves user information from the system.
96+
97+
.DESCRIPTION
98+
The Get-UserInfo function retrieves detailed information about users
99+
in the system based on specified filters.
100+
101+
.PARAMETER Username
102+
The username to retrieve information for.
103+
104+
.EXAMPLE
105+
Get-UserInfo -Username "john.doe"
106+
Retrieves information for user john.doe.
107+
108+
.OUTPUTS
109+
System.Object. Returns a custom object with user properties.
110+
#>
111+
```
112+
113+
### README Updates
114+
If your contribution adds new functionality, update the module README.md to reflect these changes.
115+
116+
### Changelog
117+
Significant changes should be noted in the CHANGELOG.md file.
118+
119+
## Testing Guidelines
120+
121+
### Required Tests
122+
All contributions must include Pester tests that:
123+
- Cover new functionality
124+
- Verify bug fixes
125+
- Maintain or improve code coverage
126+
127+
### Running Tests
128+
```powershell
129+
# Run all tests
130+
Invoke-Pester
131+
132+
# Run tests for a specific function
133+
Invoke-Pester -Path "./tests/Get-Example.Tests.ps1"
134+
```
135+
136+
### Test Structure
137+
- Tests should be in the `tests` directory
138+
- Test files should be named `<FunctionName>.Tests.ps1`
139+
- Use descriptive test names that explain what is being tested
140+
- Include both positive and negative test cases
141+
142+
## Pull Request Process
143+
144+
1. **Ensure all tests pass** locally before submitting
145+
2. **Run PSScriptAnalyzer** to check for style issues:
146+
```powershell
147+
Invoke-ScriptAnalyzer -Path ./path/to/your/script.ps1
148+
```
149+
3. **Update documentation** as needed
150+
4. **Create a pull request** with a clear title and description
151+
5. **Link any related issues** in your PR description
152+
6. **Be responsive** to code review feedback
153+
154+
### PR Description Template
155+
```
156+
## Description
157+
[Brief description of the changes]
158+
159+
## Related Issue
160+
[Link to the related issue(s)]
161+
162+
## Motivation and Context
163+
[Why is this change required? What problem does it solve?]
164+
165+
## How Has This Been Tested?
166+
[Description of tests that you ran]
167+
168+
## Types of changes
169+
- [ ] Bug fix (non-breaking change which fixes an issue)
170+
- [ ] New feature (non-breaking change which adds functionality)
171+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
172+
```
173+
174+
## Issue Reporting
175+
176+
When reporting issues:
177+
1. Use the issue template if provided
178+
2. Include PowerShell version (`$PSVersionTable`)
179+
3. Provide steps to reproduce the issue
180+
4. Include expected vs. actual behavior
181+
5. Add any error messages or screenshots
182+
183+
## Community Expectations
184+
185+
### Code of Conduct
186+
All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).
187+
188+
### Review Process
189+
- Pull requests require at least one maintainer review
190+
- Feedback should be addressed before merging
191+
- Be patient - maintainers will review PRs as time permits
192+
193+
### Recognition
194+
Contributors will be recognized in the project:
195+
- Added to CONTRIBUTORS.md file
196+
- Mentioned in release notes for significant contributions
197+
198+
## Additional Resources
199+
200+
- [PowerShell Documentation](https://docs.microsoft.com/en-us/powershell/)
201+
- [PowerShell Best Practices and Style Guide](https://github.com/PoshCode/PowerShellPracticeAndStyle)
202+
- [Writing Pester Tests](https://pester.dev/docs/quick-start)
203+
204+
---
205+
206+
Thank you for contributing to our community PowerShell module! Your efforts help make this tool better for everyone.

0 commit comments

Comments
 (0)