You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There are many ways to become involved with PowerShell including:
19
6
20
-
## Quick Start Checklist
21
-
22
-
* Review the [Contributor License Agreement][CLA] requirement.
23
-
* Get familiar with the [PowerShell repository](../docs/git).
7
+
-[Contributing to Documentation](#contributing-to-documentation)
8
+
-[Contributing to Issues](#contributing-to-issues)
9
+
-[Contributing to Code](#contributing-to-code)
24
10
25
-
## Contributing to Issues
26
-
27
-
* Review [Issue Management][issue-management].
28
-
* Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
29
-
* If you can't find your issue already,
30
-
[open a new issue](https://github.com/PowerShell/PowerShell/issues/new/choose),
31
-
making sure to follow the directions as best you can.
32
-
* If the issue is marked as [`Up-for-Grabs`][up-for-grabs],
33
-
the PowerShell Maintainers are looking for help with the issue.
34
-
* Issues marked as [`First-Time-Issue`][first-time-issue],
35
-
are identified as being easy and a great way to learn about this project and making
36
-
contributions.
11
+
Please read the rest of this document to ensure a smooth contribution process.
37
12
38
13
## Contributing to Documentation
39
14
40
-
### Contributing to documentation related to PowerShell
15
+
Contributing to the docs is an excellent way to get started with the process of making open source contributions with minimal technical skill required.
16
+
17
+
Please see the [Contributor Guide in `MicrosoftDocs/PowerShell-Docs`](https://aka.ms/PSDocsContributor).
41
18
42
-
Please see the [Contributor Guide in `MicrosoftDocs/PowerShell-Docs`](https://github.com/MicrosoftDocs/PowerShell-Docs/blob/staging/CONTRIBUTING.md).
19
+
Learn how to [Contribute to Docs like a Microsoft Insider](https://www.youtube.com/watch?v=ZQODV8krq1Q) (by @sdwheeler)
43
20
44
-
#### Quick steps if you're changing an existing cmdlet
21
+
###Updating Documentation for an existing cmdlet
45
22
46
23
If you made a change to an existing cmdlet and would like to update the documentation using PlatyPS,
47
24
here are the quick steps:
@@ -67,13 +44,13 @@ which will update the documentation for you.
67
44
made.
68
45
1. Link your Docs PR to your original change PR.
69
46
70
-
### Contributing to documentation related to maintaining or contributing to the PowerShell project
47
+
### Style notes for documentation related to maintaining or contributing to the PowerShell project
71
48
72
49
* When writing Markdown documentation, use [semantic linefeeds][].
73
50
In most cases, it means "one clause/idea per line".
74
51
* Otherwise, these issues should be treated like any other issue in this repository.
@@ -89,7 +66,7 @@ To run the spell checker, follow these steps:
89
66
90
67
If you need to add a term or disable checking part of a file see the [configuration sections of the rule](https://github.com/sapegin/textlint-rule-terminology).
91
68
92
-
####Checking links in documentation
69
+
### Checking links in documentation
93
70
94
71
Documentation is link-checked. We make use of the
95
72
`markdown-link-check` command-line tool,
@@ -102,22 +79,19 @@ To run the link-checker, follow these steps:
* run `find . \*.md -exec markdown-link-check {} \;`
104
81
105
-
## Contributing to Code
106
-
107
-
### Code Editor
108
-
109
-
You should use the multi-platform [Visual Studio Code (VS Code)][use-vscode-editor].
110
-
111
-
### Building and testing
112
-
113
-
#### Building PowerShell
114
-
115
-
Please see [Building PowerShell](../README.md#building-the-repository).
116
-
117
-
#### Testing PowerShell
118
-
119
-
Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test your build locally.
82
+
## Contributing to Issues
120
83
84
+
1. Review [Issue Management][issue-management].
85
+
1. Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
86
+
1. If you can't find your issue already,
87
+
[open a new issue](https://github.com/PowerShell/PowerShell/issues/new/choose),
88
+
making sure to follow the directions as best you can.
89
+
1. If the issue is marked as [`Up-for-Grabs`][up-for-grabs],
90
+
the PowerShell Maintainers are looking for help with the issue.
91
+
1. Issues marked as [`First-Time-Issue`][first-time-issue],
92
+
are identified as being easy and a great way to learn about this project and making
93
+
contributions.
94
+
121
95
### Finding or creating an issue
122
96
123
97
1. Follow the instructions in [Contributing to Issues][contribute-issues] to find or open an issue.
@@ -137,6 +111,59 @@ Additional references:
137
111
* GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request)
138
112
* GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
139
113
114
+
## Contributing to Code
115
+
116
+
### Quick Start Checklist
117
+
118
+
* Review the [Contributor License Agreement][CLA] requirement.
119
+
* Get familiar with the [PowerShell Repository Git Concepts](../docs/git/README.md).
120
+
* Start a [GitHub Codespace](#Dev Container) and start exploring the repository.
121
+
* Consider if what you want to do might be implementable as a [PowerShell Binary Module](https://learn.microsoft.com/powershell/scripting/developer/module/how-to-write-a-powershell-binary-module?view=powershell-7.5).
122
+
The PowerShell repository has a rigorous acceptance process due to its huge popularity and emphasis on stability and long term support, and with a binary module you can contribute to the community much more quickly.
123
+
* Pick an existing issue to work on! For instance, clarifying a confusing or unclear error message is a great starting point.
124
+
125
+
### Intro to Git and GitHub
126
+
127
+
1. Sign up for a [GitHub account](https://github.com/signup/free).
128
+
1. Learning Git and GitHub:
129
+
-[Git Basics](../docs/git/basics.md): install and getting started
130
+
-[Good Resources for Learning Git and GitHub][good-git-resources]
131
+
1. The PowerShell repository uses GitHub Flow as the primary branching strategy. [Learn about GitHub Flow](https://guides.github.com/introduction/flow/)
132
+
133
+
### Code Editing
134
+
135
+
PowerShell is primarily written in [C#](https://learn.microsoft.com/dotnet/csharp/tour-of-csharp/overview). While you can use any C# development environment you prefer, [Visual Studio Code][use-vscode-editor] is recommended.
136
+
137
+
### Dev Container
138
+
139
+
There is a PowerShell [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) which enables you get up and running quickly with a prepared Visual Studio Code environment with all the required prerequisites already installed.
140
+
141
+
[GitHub Codespaces](https://github.com/features/codespaces) is the fastest way to get started.
142
+
Codespaces allows you to start a Github-hosted devcontainer from anywhere and contribute from your browser or via Visual Studio Code remoting.
143
+
All GitHub users get 15 hours per month of a 4-core codespace for free.
144
+
145
+
To start a codespace for the PowerShell repository:
146
+
147
+
1. Go to https://github.com/PowerShell/PowerShell
148
+
1. Click the green button on the right and choose to create a codespace
149
+
150
+
151
+
1. Alternatively, just hit the comma `,` key on your keyboard which should instantly start a codespace as well.
152
+
153
+
Once the codespace starts, you can press `ctrl+shift+b` (`cmd+shift+b` on Mac) to run the default build task. If you would like to interactivey test your changes, you can press `F5` to start debugging, add breakpoints, etc.
154
+
155
+
[Learn more about how to get started with C# in Visual Studio Code](https://code.visualstudio.com/docs/csharp/get-started)
156
+
157
+
### Building and Testing
158
+
159
+
#### Building PowerShell
160
+
161
+
[Building PowerShell](../README.md#Building-Powershell) has instructions for various platforms.
162
+
163
+
#### Testing PowerShell
164
+
165
+
Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test your build locally.
166
+
140
167
### Lifecycle of a pull request
141
168
142
169
#### Before submitting
@@ -161,7 +188,7 @@ Additional references:
161
188
In such case, it's better to split the PR to multiple smaller ones.
162
189
For large features, try to approach it in an incremental way, so that each PR won't be too big.
163
190
* If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.
164
-
See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell).
191
+
See [Contributing to documentation related to PowerShell](#contributing-to-documentation).
165
192
* Add a meaningful title of the PR describing what change you want to check in.
166
193
Don't simply put: "Fix issue #5".
167
194
Also don't directly use the issue title as the PR title.
@@ -191,10 +218,10 @@ Additional references:
191
218
As an example, this requirement includes any changes to cmdlets (including cmdlet parameters) and features which have associated about_* topics.
192
219
While not required, we appreciate any contributors who add this label and create the issue themselves.
193
220
Even better, all contributors are free to contribute the documentation themselves.
194
-
(See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell) for more info.)
221
+
(See [Contributing to documentation related to PowerShell](#contributing-to-documentation) for more info.)
195
222
* If your change adds a new source file, ensure the appropriate copyright and license headers is on top.
196
223
It is standard practice to have both a copyright and license notice for each source file.
197
-
* For `.h`, `.cpp`, and `.cs` files use the copyright header with empty line after it:
224
+
* For `.cs` files use the copyright header with empty line after it:
198
225
199
226
```c#
200
227
// Copyright (c) Microsoft Corporation.
@@ -266,7 +293,7 @@ Additional references:
266
293
267
294
#### Pull Request - Roles and Responsibilities
268
295
269
-
1. The PR *author* is responsible for moving the PR forward to get it Approved.
296
+
1. The PR *author* is responsible for moving the PR forward to get it approved.
270
297
This includes addressing feedback within a timely period and indicating feedback has been addressed by adding a comment and mentioning the specific *reviewers*.
271
298
When updating your pull request, please **create new commits** and **don't rewrite the commits history**.
272
299
This way it's very easy for the reviewers to see diff between iterations.
@@ -300,7 +327,7 @@ In these cases:
300
327
Mention the original pull request ID in the description of the new issue and close the abandoned pull request.
301
328
- If the changes in an abandoned pull request are no longer needed (e.g. due to refactoring of the codebase or a design change), *assignee* will simply close the pull request.
302
329
303
-
## Making Breaking Changes
330
+
###Making Breaking Changes
304
331
305
332
When you make code changes,
306
333
please pay attention to these that can affect the [Public Contract][breaking-changes-contract].
@@ -309,12 +336,12 @@ Before making changes to the code,
309
336
first review the [breaking changes contract][breaking-changes-contract]
310
337
and follow the guidelines to keep PowerShell backward compatible.
311
338
312
-
## Making Design Changes
339
+
###Making Design Changes
313
340
314
341
To add new features such as cmdlets or making design changes,
315
342
please follow the [PowerShell Request for Comments (RFC)][rfc-process] process.
316
343
317
-
## Common Engineering Practices
344
+
###Common Engineering Practices
318
345
319
346
Other than the guidelines for [coding][coding-guidelines],
320
347
the [RFC process][rfc-process] for design,
@@ -366,7 +393,7 @@ is also appropriate, as is using Markdown syntax.
366
393
Before you invest a large amount of time,
367
394
file an issue and start a discussion with the community.
368
395
369
-
## Contributor License Agreement (CLA)
396
+
###Contributor License Agreement (CLA)
370
397
371
398
To speed up the acceptance of any contribution to any PowerShell repositories,
372
399
you should sign the Microsoft [Contributor License Agreement (CLA)](https://cla.microsoft.com/) ahead of time.
@@ -404,7 +431,7 @@ Repeat offenses may result in a permanent ban from the PowerShell org.
Want to contribute to PowerShell? Please start with the [Contribution Guide][] to learn how to develop and contribute.
82
+
83
+
If you are developing .NET Core C# applications targeting PowerShell Core, [check out our FAQ][] to learn more about the PowerShell SDK NuGet package.
84
+
85
+
Also, make sure to check out our [PowerShell-RFC repository](https://github.com/powershell/powershell-rfc) for request-for-comments (RFC) documents to submit and give comments on proposed and future designs.
86
+
87
+
[Contribution Guide]: .github/CONTRIBUTING.md
88
+
[check out our FAQ]: docs/FAQ.md#where-do-i-get-the-powershell-core-sdk-package
For more information, see [working with the PowerShell repository](https://github.com/PowerShell/PowerShell/tree/master/docs/git).
102
112
103
-
## Developing and Contributing
104
-
105
-
Please look into the [Contribution Guide][] to know how to develop and contribute.
106
-
If you are developing .NET Core C# applications targeting PowerShell Core, [check out our FAQ][] to learn more about the PowerShell SDK NuGet package.
107
-
108
-
Also, make sure to check out our [PowerShell-RFC repository](https://github.com/powershell/powershell-rfc) for request-for-comments (RFC) documents to submit and give comments on proposed and future designs.
> The PowerShell container images are now [maintained by the .NET team](https://github.com/PowerShell/Announcements/issues/75). The containers at `mcr.microsoft.com/powershell` are currently not maintained.
126
129
127
130
License: By requesting and using the Container OS Image for Windows containers, you acknowledge, understand, and consent to the Supplemental License Terms available on [Microsoft Artifact Registry][mcr].
0 commit comments