MegaBites-AI/Windows-powershell

1# Contributing to PowerShell2 3We welcome and appreciate contributions from the community!4 5There are many ways to become involved with PowerShell including:6 7- [Contributing to Documentation](#contributing-to-documentation)8- [Contributing to Issues](#contributing-to-issues)9- [Contributing to Code](#contributing-to-code)10 11Please read the rest of this document to ensure a smooth contribution process.12 13## Contributing to Documentation14 15Contributing to the docs is an excellent way to get started with the process of making open source contributions with minimal technical skill required.16 17Please see the [Contributor Guide in `MicrosoftDocs/PowerShell-Docs`](https://aka.ms/PSDocsContributor).18 19Learn how to [Contribute to Docs like a Microsoft Insider](https://www.youtube.com/watch?v=ZQODV8krq1Q) (by @sdwheeler)20 21### Updating Documentation for an existing cmdlet22 23If you made a change to an existing cmdlet and would like to update the documentation using PlatyPS,24here are the quick steps:25 261. Install27`PlatyPS`28if you don't have it -29`Install-Module PlatyPS`.301. Clone the31[`MicrosoftDocs/PowerShell-Docs`](https://github.com/MicrosoftDocs/PowerShell-Docs)32repository if you don't already have it.331. Start your local build of PowerShell34(with the change to the cmdlet you made).351. Find the cmdlet's Markdown file in PowerShell Docs - usually under36`PowerShell-Docs/reference/<latest powershell version>/<module cmdlet is a part of>/<your changed cmdlet>.md`37(Ex. `PowerShell-Docs/reference/7/Microsoft.PowerShell.Utility/Select-String.md`)381. Run39`Update-MarkdownHelp -Path <path to cmdlet Markdown file>`40which will update the documentation for you.411. Make any additional changes needed for the cmdlet to be properly documented.421. Send a Pull Request to the PowerShell Docs repository with the changes that43`PlatyPS`44made.451. Link your Docs PR to your original change PR.46 47### Style notes for documentation related to maintaining or contributing to the PowerShell project48 49* When writing Markdown documentation, use [semantic linefeeds][].50  In most cases, it means "one clause/idea per line".51* Otherwise, these issues should be treated like any other issue in this repository.52 53### Spell checking documentation54 55Documentation is spellchecked. We use the56[textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) command-line tool,57which can be run in interactive mode to correct typos.58 59To run the spell checker, follow these steps:60 61* install [Node.js](https://nodejs.org/en/) (v10 or up)62* install [textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) by63  `npm install -g textlint textlint-rule-terminology`64* run `textlint --rule terminology <changedFileName>`,65  adding `--fix` will accept all the recommendations.66 67If 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).68 69### Checking links in documentation70 71Documentation is link-checked. We make use of the72`markdown-link-check` command-line tool,73which can be run to see if any links are dead.74 75To run the link-checker, follow these steps:76 77* install [Node.js](https://nodejs.org/en/) (v10 or up)78* install `markdown-link-check` by79  `npm install -g markdown-link-check@3.8.5`80* run `find . \*.md -exec markdown-link-check {} \;`81 82## Contributing to Issues83 841. Review [Issue Management][issue-management].851. Check if the issue you are going to file already exists in our [GitHub issues][open-issue].861. 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.891. If the issue is marked as [`Up-for-Grabs`][up-for-grabs],90  the PowerShell Maintainers are looking for help with the issue.911. 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 making93  contributions.94 95### Finding or creating an issue96 971. Follow the instructions in [Contributing to Issues][contribute-issues] to find or open an issue.981. Mention in the issue that you are working on the issue and ask `@powershell/powershell` for an assignment.99 100### Forks and Pull Requests101 102GitHub fosters collaboration through the notion of [pull requests][using-prs].103On GitHub, anyone can [fork][fork-a-repo] an existing repository104into their own user account, where they can make private changes to their fork.105To contribute these changes back into the original repository,106a user simply creates a pull request in order to "request" that the changes be taken "upstream".107 108Additional references:109 110* GitHub's guide on [forking](https://guides.github.com/activities/forking/)111* GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request)112* GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)113 114## Contributing to Code115 116### Quick Start Checklist117 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 GitHub126 1271. Sign up for a [GitHub account](https://github.com/signup/free).1281. Learning Git and GitHub:129    - [Git Basics](../docs/git/basics.md): install and getting started130    - [Good Resources for Learning Git and GitHub][good-git-resources]1311. The PowerShell repository uses GitHub Flow as the primary branching strategy. [Learn about GitHub Flow](https://guides.github.com/introduction/flow/)132 133### Code Editing134 135PowerShell 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 Container138 139There 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.142Codespaces allows you to start a Github-hosted devcontainer from anywhere and contribute from your browser or via Visual Studio Code remoting.143All GitHub users get 15 hours per month of a 4-core codespace for free.144 145To start a codespace for the PowerShell repository:146 1471. Go to https://github.com/PowerShell/PowerShell1481. Click the green button on the right and choose to create a codespace149 150   ![alt text](Images/Codespaces.png)1511. Alternatively, just hit the comma `,` key on your keyboard which should instantly start a codespace as well.152 153Once 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 Testing158 159#### Building PowerShell160 161[Building PowerShell](../README.md#Building-Powershell) has instructions for various platforms.162 163#### Testing PowerShell164 165Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test your build locally.166 167### Lifecycle of a pull request168 169#### Before submitting170 171* If your change would fix a security vulnerability,172  first follow the [vulnerability issue reporting policy][vuln-reporting], before submitting a PR.173* To avoid merge conflicts, make sure your branch is rebased on the `master` branch of this repository.174* Many code changes will require new tests,175  so make sure you've added a new test if existing tests do not effectively test the code changed.176* Clean up your commit history.177  Each commit should be a **single complete** change.178  This discipline is important when reviewing the changes as well as when using `git bisect` and `git revert`.179 180#### Pull request - Submission181 182**Always create a pull request to the `master` branch of this repository**.183 184![GitHub-PR.png](Images/GitHub-PR.png)185 186* It's recommended to avoid a PR with too many changes.187  A large PR not only stretches the review time, but also makes it much harder to spot issues.188  In such case, it's better to split the PR to multiple smaller ones.189  For large features, try to approach it in an incremental way, so that each PR won't be too big.190* If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.191  See [Contributing to documentation related to PowerShell](#contributing-to-documentation).192* Add a meaningful title of the PR describing what change you want to check in.193  Don't simply put: "Fix issue #5".194  Also don't directly use the issue title as the PR title.195  An issue title is to briefly describe what is wrong, while a PR title is to briefly describe what is changed.196  A better example is: "Add Ensure parameter to New-Item cmdlet", with "Fix #5" in the PR's body.197* When you create a pull request,198  include a summary about your changes in the PR description.199  The description is used to create changelogs,200  so try to have the first sentence explain the benefit to end users.201  If the changes are related to an existing GitHub issue,202  please reference the issue in the PR description (e.g. ```Fix #11```).203  See [this][closing-via-message] for more details.204 205* Please use the present tense and imperative mood when describing your changes:206  * Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2".207  * Instead of "Fixed for server connection issue", write "Fix server connection issue".208 209  This form is akin to giving commands to the codebase210  and is recommended by the Git SCM developers.211  It is also used in the [Git commit messages](#common-engineering-practices).212* If the change is related to a specific resource, please prefix the description with the resource name:213  * Instead of "New parameter 'ConnectionCredential' in New-SqlConnection",214  write "New-SqlConnection: add parameter 'ConnectionCredential'".215* If your change warrants an update to user-facing documentation,216  a Maintainer will add the `Documentation Needed` label to your PR and add an issue to the [PowerShell-Docs repository][PowerShell-Docs],217  so that we make sure to update official documentation to reflect your contribution.218  As an example, this requirement includes any changes to cmdlets (including cmdlet parameters) and features which have associated about_* topics.219  While not required, we appreciate any contributors who add this label and create the issue themselves.220  Even better, all contributors are free to contribute the documentation themselves.221  (See [Contributing to documentation related to PowerShell](#contributing-to-documentation) for more info.)222* If your change adds a new source file, ensure the appropriate copyright and license headers is on top.223  It is standard practice to have both a copyright and license notice for each source file.224  * For `.cs` files use the copyright header with empty line after it:225 226    ```c#227        // Copyright (c) Microsoft Corporation.228        // Licensed under the MIT License.229        <Add empty line here>230    ```231 232  * For `.ps1` and `.psm1` files use the copyright header with empty line after it:233 234    ```powershell235        # Copyright (c) Microsoft Corporation.236        # Licensed under the MIT License.237        <Add empty line here>238    ```239 240* If your change adds a new module manifest (.psd1 file), ensure that:241 242  ```powershell243  Author = "PowerShell"244  Company = "Microsoft Corporation"245  Copyright = "Copyright (c) Microsoft Corporation."246  ```247 248  is at the top.249 250### Pull Request - Work in Progress251 252* If your pull request is not ready to merge, please add the prefix `WIP:` to the beginning of the title and remove the prefix when the PR is ready.253 254#### Pull Request - Automatic Checks255 256* If this is your first contribution to PowerShell,257  you may be asked to sign a [Contribution Licensing Agreement][CLA] (CLA)258  before your changes will be accepted.259* Make sure you follow the [Common Engineering Practices](#common-engineering-practices)260  and [testing guidelines](../docs/testing-guidelines/testing-guidelines.md).261* After submitting your pull request,262  our [CI system (Azure DevOps Pipelines)][ci-system]263  will run a suite of tests and automatically update the status of the pull request.264* Our CI contains automated spell checking and link checking for Markdown files. If there is any false-positive,265  [run the spell checker command-line tool in interactive mode](#spell-checking-documentation)266  to add words to the `.spelling` file.267 268  You could update the `.spelling` file manually in accordance with messages in the test log file, or269  [run the spell checker command-line tool in interactive mode](#spell-checking-documentation)270  to add the false-positive words directly.271 272#### Pull Request - Workflow273 2741. The PR *author* creates a pull request from a fork.2751. The *author* ensures that their pull request passes the [CI system][ci-system] build.276   - If the build fails, a [Repository Maintainer][repository-maintainer] adds the `Review - waiting on author` label to the pull request.277   The *author* can then continue to update the pull request until the build passes.2781. If the *author* knows whom should participate in the review, they should add them otherwise they can add the recommended *reviewers*.2791. Once the build passes, if there is not sufficient review, the *maintainer* adds the `Review - needed` label.2801. An [Area Expert][area-expert] should also review the pull request.281   - If the *author* does not meet the *reviewer*'s standards, the *reviewer* makes comments. A *maintainer* then removes the `Review - needed` label and adds282   the `Review - waiting on author` label. The *author* must address the comments and repeat from step 2.283   - If the *author* meets the *reviewer*'s standards, the *reviewer* approves the PR. A maintainer then removes the `need review` label.2841. Once the code review is completed, a *maintainer* merges the pull request after one business day to allow for additional critical feedback.285 286#### Pull Request - Roles and Responsibilities287 2881. The PR *author* is responsible for moving the PR forward to get it approved.289   This includes addressing feedback within a timely period and indicating feedback has been addressed by adding a comment and mentioning the specific *reviewers*.290   When updating your pull request, please **create new commits** and **don't rewrite the commits history**.291   This way it's very easy for the reviewers to see diff between iterations.292   If you rewrite the history in the pull request, review could be much slower.293   The PR is likely to be squash-merged to master by the *assignee*.2941. *Reviewers* are anyone who wants to contribute.295   They are responsible for ensuring the code: addresses the issue being fixed, does not create new issues (functional, performance, reliability, or security), and implements proper design.296   *Reviewers* should use the `Review changes` drop down to indicate they are done with their review.297   - `Request changes` if you believe the PR merge should be blocked if your feedback is not addressed,298   - `Approve` if you believe your feedback has been addressed or the code is fine as-is, it is customary (although not required) to leave a simple "Looks good to me" (or "LGTM") as the comment for approval.299   - `Comment` if you are making suggestions that the *author* does not have to accept.300   Early in the review, it is acceptable to provide feedback on coding formatting based on the published [Coding Guidelines][coding-guidelines], however,301   after the PR has been approved, it is generally *not* recommended to focus on formatting issues unless they go against the [Coding Guidelines][coding-guidelines].302   Non-critical late feedback (after PR has been approved) can be submitted as a new issue or new pull request from the *reviewer*.3031. *Assignees* who are always *Maintainers* ensure that proper review has occurred and if they believe one approval is not sufficient, the *maintainer* is responsible to add more reviewers.304   An *assignee* may also be a reviewer, but the roles are distinct.305   Once the PR has been approved and the CI system is passing, the *assignee* will merge the PR after giving one business day for any critical feedback.306   For more information on the PowerShell Maintainers' process, see the [documentation](../docs/maintainers).307 308#### Pull Requests - Abandoned309 310A pull request with the label `Review - waiting on author` for **more than two weeks** without a word from the author is considered abandoned.311 312In these cases:313 3141. *Assignee* will ping the author of PR to remind them of pending changes.315   - If the *author* responds, it's no longer an abandoned; the pull request proceeds as normal.3161. If the *author* does not respond **within a week**:317   - If the *reviewer*'s comments are very minor, merge the change, fix the code immediately, and create a new PR with the fixes addressing the minor comments.318   - If the changes required to merge the pull request are significant but needed, *assignee* creates a new branch with the changes and open an issue to merge the code into the dev branch.319   Mention the original pull request ID in the description of the new issue and close the abandoned pull request.320   - 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.321 322### Making Breaking Changes323 324When you make code changes,325please pay attention to these that can affect the [Public Contract][breaking-changes-contract].326For example, changing PowerShell parameters, APIs, or protocols break the public contract.327Before making changes to the code,328first review the [breaking changes contract][breaking-changes-contract]329and follow the guidelines to keep PowerShell backward compatible.330 331### Making Design Changes332 333To add new features such as cmdlets or making design changes,334please follow the [PowerShell Request for Comments (RFC)][rfc-process] process.335 336### Common Engineering Practices337 338Other than the guidelines for [coding][coding-guidelines],339the [RFC process][rfc-process] for design,340[documentation](#contributing-to-documentation) and [testing](../docs/testing-guidelines/testing-guidelines.md) discussed above,341we encourage contributors to follow these common engineering practices:342 343* Format commit messages following these guidelines:344 345```text346Summarize change in 50 characters or less347 348Similar to email, this is the body of the commit message,349and the above is the subject.350Always leave a single blank line between the subject and the body351so that `git log` and `git rebase` work nicely.352 353The subject of the commit should use the present tense and354imperative mood, like issuing a command:355 356> Makes abcd do wxyz357 358The body should be a useful message explaining359why the changes were made.360 361If significant alternative solutions were available,362explain why they were discarded.363 364Keep in mind that the person most likely to refer to your commit message365is you in the future, so be detailed!366 367As Git commit messages are most frequently viewed in the terminal,368you should wrap all lines around 72 characters.369 370Using semantic line feeds (breaks that separate ideas)371is also appropriate, as is using Markdown syntax.372```373 374* These are based on Tim Pope's [guidelines](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),375  Git SCM [submitting patches](https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches),376  Brandon Rhodes' [semantic linefeeds][],377  and John Gruber's [Markdown syntax](https://daringfireball.net/projects/markdown/syntax).378* Don't commit code that you didn't write.379  If you find code that you think is a good fit to add to PowerShell,380  file an issue and start a discussion before proceeding.381* Create and/or update tests when making code changes.382* Run tests and ensure they are passing before opening a pull request.383* All pull requests **must** pass CI systems before they can be approved.384* Avoid making big pull requests.385  Before you invest a large amount of time,386  file an issue and start a discussion with the community.387 388### Contributor License Agreement (CLA)389 390To speed up the acceptance of any contribution to any PowerShell repositories,391you should sign the Microsoft [Contributor License Agreement (CLA)](https://cla.microsoft.com/) ahead of time.392If you've already contributed to PowerShell or Microsoft repositories in the past, congratulations!393You've already completed this step.394This a one-time requirement for the PowerShell project.395Signing the CLA process is simple and can be done in less than a minute.396You don't have to do this up-front.397You can simply clone, fork, and submit your pull request as usual.398When your pull request is created, it is checked by the CLA bot.399If you have signed the CLA, the status check will be set to `passing`.  Otherwise, it will stay at `pending`.400Once you sign a CLA, all your existing and future pull requests will have the status check automatically set at `passing`.401 402## Code of Conduct Enforcement403 404Reports of abuse will be reviewed by the [PowerShell Committee][ps-committee] and if it has been determined that violations of the405[Code of Conduct](../CODE_OF_CONDUCT.md) has occurred, then a temporary ban may be imposed.406The duration of the temporary ban will depend on the impact and/or severity of the infraction.407This can vary from 1 day, a few days, a week, and up to 30 days.408Repeat offenses may result in a permanent ban from the PowerShell org.409 410[running-tests-outside-of-ci]: ../docs/testing-guidelines/testing-guidelines.md#running-tests-outside-of-ci411[issue-management]: ../docs/maintainers/issue-management.md412[vuln-reporting]: ./SECURITY.md413[using-prs]: https://help.github.com/articles/using-pull-requests/414[fork-a-repo]: https://help.github.com/articles/fork-a-repo/415[closing-via-message]: https://help.github.com/articles/closing-issues-via-commit-messages/416[CLA]: #contributor-license-agreement-cla417[ci-system]: ../docs/testing-guidelines/testing-guidelines.md#ci-system418[good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/419[contribute-issues]: #contributing-to-issues420[open-issue]: https://github.com/PowerShell/PowerShell/issues421[up-for-grabs]: https://github.com/powershell/powershell/issues?q=is%3Aopen+is%3Aissue+label%3AUp-for-Grabs422[semantic linefeeds]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/423[PowerShell-Docs]: https://github.com/powershell/powershell-docs/424[use-vscode-editor]: https://learn.microsoft.com/dotnet/core/tutorials/with-visual-studio-code425[repository-maintainer]: ../docs/community/governance.md#repository-maintainers426[area-expert]: ../.github/CODEOWNERS427[first-time-issue]: https://github.com/powershell/powershell/issues?q=is%3Aopen+is%3Aissue+label%3AFirst-Time-Issue428[coding-guidelines]: ../docs/dev-process/coding-guidelines.md429[breaking-changes-contract]: ../docs/dev-process/breaking-change-contract.md430[rfc-process]: https://github.com/PowerShell/PowerShell-RFC431[ps-committee]: ../docs/community/governance.md#powershell-committee432