Skip to content

Latest commit

 

History

History
131 lines (102 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

131 lines (102 loc) · 6.21 KB
Raw

Contributing to PSReadLine

We welcome and appreciate contributions from the community. There are many ways to become involved with PSReadLine, including

  • Filing issues
  • Joining in design conversations
  • Writing and improving documentation
  • Contributing to the code

Please read the rest of this document to ensure a smooth contribution process.

Intro to Git and GitHub

Contributor License Agreement (CLA)

To speed up the acceptance of any contribution to any PowerShell repositories, you should sign the Microsoft Contributor License Agreement (CLA) ahead of time. If you've already contributed to PowerShell or Microsoft repositories in the past, congratulations! You've already completed this step. This a one-time requirement for the PowerShell projects. Signing the CLA process is simple and can be done in less than a minute. You don't have to do this up-front. You can simply clone, fork, and submit your pull request as usual. When your pull request is created, it is checked by the CLA bot. If you have signed the CLA, the status check will be set to passing. Otherwise, it will stay at pending. Once you sign a CLA, all your existing and future pull requests will have the status check automatically set at passing.

Contributing to Issues

  • Check if the issue you are going to file already exists in our GitHub issues.
  • If you can't find your issue already, open a new issue, making sure to follow the directions as best you can.
  • If the issue is marked as Up-for-Grabs, the PSReadLine Maintainers are looking for help with the issue.

Contributing to Documentation

The documentation is located in the docs folder. The markdown files there are converted to the PowerShell help.xml file via platyPS during the build.

Contributing to Code

Forks and Pull Requests

GitHub fosters collaboration through the notion of pull requests. On GitHub, anyone can fork an existing repository into their own user account, where they can make private changes to their fork. To contribute these changes back into the original repository, a user simply creates a pull request in order to "request" that the changes be taken "upstream".

Additional references:

Bootstrap, Build and Test

To build PSReadLine on Windows, Linux, or macOS, you must have the following installed:

  • .NET Core SDK 2.1.802 or a newer version
  • The PowerShell modules InvokeBuild and platyPS

The build script build.ps1 can be used to bootstrap, build and test the project.

  • Bootstrap: ./build.ps1 -Bootstrap
  • Build:
    • Targeting .NET 4.6.2 (Windows only): ./build.ps1 -Configuration Debug -Framework net462
    • Targeting .NET Core: ./build.ps1 -Configuration Debug -Framework netcoreapp2.1
  • Test:
    • Targeting .NET 4.6.2 (Windows only): ./build.ps1 -Test -Configuration Debug -Framework net462
    • Targeting .NET Core: ./build.ps1 -Test -Configuration Debug -Framework netcoreapp2.1

After build, the produced artifacts can be found at <your-local-repo-root>/bin/Debug.

Submitting Pull Request

  • If your change would fix a security vulnerability, first follow the vulnerability issue reporting policy, before submitting a PR.

  • To avoid merge conflicts, make sure your branch is rebased on the master branch of this repository.

  • Many code changes will require new tests, so make sure you've added a new test if existing tests do not effectively cover the code changed.

  • If your change adds a new source file, ensure the appropriate copyright and license headers is on top. It is standard practice to have both a copyright and license notice for each source file.

    • For .cs files use the copyright header with empty line after it:
        // Copyright (c) Microsoft Corporation.
    // Licensed under the 2-Clause BSD License.
    <Add empty line here>
    • For .ps1 files use the copyright header with empty line after it:
        # Copyright (c) Microsoft Corporation.
    # Licensed under the 2-Clause BSD License.
    <Add empty line here>

  • If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.

  • When you create a pull request, use a meaningful title for the PR describing what change you want to check in. Make sure you also include a summary about your changes in the PR description. The description is used to create change logs, so try to have the first sentence explain the benefit to end users. If the changes are related to an existing GitHub issue, please reference the issue in the PR description (e.g. Fix #11). See this for more details.