Skip to content

Commit a24be79

Browse files
daxian-dbwdaxian-dbw
authored
Add CONTRIBUTING.md (#1419)
1 parent 59bff8a commit a24be79

File tree

2 files changed

+162
-15
lines changed

2 files changed

+162
-15
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Contributing to PSReadLine
2+
3+
We welcome and appreciate contributions from the community.
4+
There are many ways to become involved with PSReadLine, including
5+
6+
- Filing issues
7+
- Joining in design conversations
8+
- Writing and improving documentation
9+
- Contributing to the code
10+
11+
Please read the rest of this document to ensure a smooth contribution process.
12+
13+
## Intro to Git and GitHub
14+
15+
* Make sure you have a [GitHub account](https://github.com/signup/free).
16+
* Learning Git:
17+
* GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources]
18+
* [Git Basics][git-basics]: install and getting started
19+
* [GitHub Flow Guide](https://guides.github.com/introduction/flow/):
20+
step-by-step instructions of GitHub Flow
21+
22+
## Contributor License Agreement (CLA)
23+
24+
To speed up the acceptance of any contribution to any PowerShell repositories,
25+
you should sign the [Microsoft Contributor License Agreement (CLA)][cla] ahead of time.
26+
If you've already contributed to PowerShell or Microsoft repositories in the past, congratulations!
27+
You've already completed this step.
28+
This a one-time requirement for the PowerShell projects.
29+
Signing the CLA process is simple and can be done in less than a minute.
30+
You don't have to do this up-front.
31+
You can simply clone, fork, and submit your pull request as usual.
32+
When your pull request is created, it is checked by the CLA bot.
33+
If you have signed the CLA, the status check will be set to `passing`. Otherwise, it will stay at `pending`.
34+
Once you sign a CLA, all your existing and future pull requests will have the status check automatically set at `passing`.
35+
36+
## Contributing to Issues
37+
38+
* Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
39+
* If you can't find your issue already,
40+
[open a new issue](https://github.com/PowerShell/PSReadLine/issues/new/choose),
41+
making sure to follow the directions as best you can.
42+
* If the issue is marked as [Up-for-Grabs][up-for-grabs],
43+
the PSReadLine Maintainers are looking for help with the issue.
44+
45+
## Contributing to Documentation
46+
47+
The documentation is located in the [docs][psreadline-docs] folder.
48+
The markdown files there are converted to the PowerShell `help.xml` file via [platyPS][platy-ps] during the build.
49+
50+
## Contributing to Code
51+
52+
### Forks and Pull Requests
53+
54+
GitHub fosters collaboration through the notion of [pull requests][using-prs].
55+
On GitHub, anyone can [fork][fork-a-repo] an existing repository
56+
into their own user account, where they can make private changes to their fork.
57+
To contribute these changes back into the original repository,
58+
a user simply creates a pull request in order to "request" that the changes be taken "upstream".
59+
60+
Additional references:
61+
62+
* GitHub's guide on [forking](https://guides.github.com/activities/forking/)
63+
* GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request)
64+
* GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
65+
66+
### Bootstrap, Build and Test
67+
68+
To build `PSReadLine` on Windows, Linux, or macOS,
69+
you must have the following installed:
70+
71+
* .NET Core SDK 2.1.802 or [a newer version](https://www.microsoft.com/net/download)
72+
* The PowerShell modules `InvokeBuild` and `platyPS`
73+
74+
The build script `build.ps1` can be used to bootstrap, build and test the project.
75+
76+
* Bootstrap: `./build.ps1 -Bootstrap`
77+
* Build:
78+
* Targeting .NET 4.6.1 (Windows only): `./build.ps1 -Configuration Debug -Framework net461`
79+
* Targeting .NET Core: `./build.ps1 -Configuration Debug -Framework netcoreapp2.1`
80+
* Test:
81+
* Targeting .NET 4.6.1 (Windows only): `./build.ps1 -Test -Configuration Debug -Framework net461`
82+
* Targeting .NET Core: `./build.ps1 -Test -Configuration Debug -Framework netcoreapp2.1`
83+
84+
After build, the produced artifacts can be found at `<your-local-repo-root>/bin/Debug`.
85+
86+
### Submitting Pull Request
87+
88+
* If your change would fix a security vulnerability,
89+
first follow the [vulnerability issue reporting policy][vuln-reporting], before submitting a PR.
90+
* To avoid merge conflicts, make sure your branch is rebased on the `master` branch of this repository.
91+
* Many code changes will require new tests,
92+
so make sure you've added a new test if existing tests do not effectively cover the code changed.
93+
* If your change adds a new source file, ensure the appropriate copyright and license headers is on top.
94+
It is standard practice to have both a copyright and license notice for each source file.
95+
* For `.cs` files use the copyright header with empty line after it:
96+
97+
```c#
98+
// Copyright (c) Microsoft Corporation.
99+
// Licensed under the 2-Clause BSD License.
100+
<Add empty line here>
101+
```
102+
103+
* For `.ps1` files use the copyright header with empty line after it:
104+
105+
```powershell
106+
# Copyright (c) Microsoft Corporation.
107+
# Licensed under the 2-Clause BSD License.
108+
<Add empty line here>
109+
```
110+
* If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.
111+
* When you create a pull request,
112+
use a meaningful title for the PR describing what change you want to check in.
113+
Make sure you also include a summary about your changes in the PR description.
114+
The description is used to create change logs,
115+
so try to have the first sentence explain the benefit to end users.
116+
If the changes are related to an existing GitHub issue,
117+
please reference the issue in the PR description (e.g. ```Fix #11```).
118+
See [this][closing-via-message] for more details.
119+
120+
121+
[up-for-grabs]: https://github.com/PowerShell/PSReadLine/issues?q=is%3Aopen+is%3Aissue+label%3AUp-for-Grabs
122+
[good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/
123+
[git-basics]: https://github.com/PowerShell/PowerShell/blob/master/docs/git/basics.md
124+
[cla]: https://cla.microsoft.com/
125+
[open-issue]: https://github.com/PowerShell/PSReadLine/issues
126+
[psreadline-docs]: https://github.com/PowerShell/PSReadLine/tree/master/docs
127+
[platy-ps]: https://www.powershellgallery.com/packages/platyPS
128+
[using-prs]: https://help.github.com/articles/using-pull-requests/
129+
[fork-a-repo]: https://help.github.com/articles/fork-a-repo/
130+
[vuln-reporting]: https://github.com/PowerShell/PowerShell/blob/master/.github/SECURITY.md
131+
[closing-via-message]: https://help.github.com/articles/closing-issues-via-commit-messages/

‎README.md

Lines changed: 31 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -206,31 +206,47 @@ If you want to change the command line in some unimplmented way in your custom k
206206
[Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition
207207
```
208208

209-
## Building
209+
## Developing and Contributing
210210

211-
### Prerequisites
211+
Please see the [Contribution Guide][] for how to develop and contribute.
212212

213-
To build `PSReadLine` on Windows, Linux, or macOS, you must have [.NET Core SDK 2.1.802 or newer](https://www.microsoft.com/net/download) installed.
214-
The build script also depends on [`InvokeBuild`](https://www.powershellgallery.com/packages/InvokeBuild) which can be installed using:
213+
### Building
215214

216-
```powershell
217-
install-module invokebuild -scope currentuser
218-
```
215+
To build `PSReadLine` on Windows, Linux, or macOS,
216+
you must have the following installed:
219217

220-
### Building and running tests
218+
* .NET Core SDK 2.1.802 or [a newer version](https://www.microsoft.com/net/download)
219+
* The PowerShell modules `InvokeBuild` and `platyPS`
221220

222-
You can create a new build and run tests by simply running within PowerShell:
221+
The build script `build.ps1` can be used to bootstrap, build and test the project.
223222

224-
```powershell
225-
invoke-build
226-
```
223+
* Bootstrap: `./build.ps1 -Bootstrap`
224+
* Build:
225+
* Targeting .NET 4.6.1 (Windows only): `./build.ps1 -Configuration Debug -Framework net461`
226+
* Targeting .NET Core: `./build.ps1 -Configuration Debug -Framework netcoreapp2.1`
227+
* Test:
228+
* Targeting .NET 4.6.1 (Windows only): `./build.ps1 -Test -Configuration Debug -Framework net461`
229+
* Targeting .NET Core: `./build.ps1 -Test -Configuration Debug -Framework netcoreapp2.1`
230+
231+
After build, the produced artifacts can be found at `<your-local-repo-root>/bin/Debug`.
227232

228-
After a successful build, the tests are automatically run.
233+
[Contribution Guide]: https://github.com/PowerShell/PSReadLine/blob/master/.github/CONTRIBUTING.md
229234

230235
## Change Log
231236

232237
The change log is available [here](https://github.com/PowerShell/PSReadLine/blob/master/PSReadLine/Changes.txt).
233238

234-
## License
239+
## Licensing
240+
241+
PSReadLine is licensed under the [2-Clause BSD License][].
242+
243+
[2-Clause BSD License]: https://github.com/PowerShell/PSReadLine/blob/master/PSReadLine/License.txt
244+
245+
## Code of Conduct
246+
247+
This project has adopted the [Microsoft Open Source Code of Conduct][conduct-code].
248+
For more information see the [Code of Conduct FAQ][conduct-FAQ] or contact [[email protected]][conduct-email] with any additional questions or comments.
235249

236-
The license is available [here](https://github.com/PowerShell/PSReadLine/blob/master/PSReadLine/License.txt).
250+
[conduct-code]: https://opensource.microsoft.com/codeofconduct/
251+
[conduct-FAQ]: https://opensource.microsoft.com/codeofconduct/faq/
252+
[conduct-email]: mailto:[email protected]

0 commit comments

Comments
 (0)