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
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+71-1Lines changed: 71 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,6 +43,8 @@ Be aware that the `@` symbol tags users on GitHub, so __always__ surround packag
43
43
44
44
### Code
45
45
46
+
> By contributing code to the project, you are agreeing to release it under the project [license][stdlib-license].
47
+
46
48
__Before__ contributing code, be sure to
47
49
48
50
* read and understand the [licensing terms][stdlib-license].
@@ -71,6 +73,11 @@ If you are unfamiliar with [git][git], the version control system used by GitHub
71
73
Next, take a look around the project, noting the style and organization of documentation, tests, examples, benchmarks, and source implementations. Consistency is highly __prioritized__ within stdlib. Thus, the more you are able to match and adhere to project conventions and style, the more likely your contribution will be accepted. While we have done our best to automate linting and style guidelines, such automation is not perfect and cannot adequately capture the inevitable exceptions and nuance to many rules. In short, the more you study existing practice, the better prepared you will be to contribute to stdlib.
72
74
73
75
76
+
#### Step 0: GitHub
77
+
78
+
Create a [GitHub account][github-signup]. The project uses GitHub exclusively for hosting source code, managing issues and pull requests, triggering continuous integration, and reporting.
79
+
80
+
74
81
#### Step 1: Fork
75
82
76
83
[Fork][github-fork] the repository on GitHub and clone the repository to your local machine.
@@ -79,7 +86,7 @@ Next, take a look around the project, noting the style and organization of docum
where `<username>` is your GitHub username (assuming you are using GitHub to manage public repositories). The repository has a large commit history, leading to slow download times. If you are not interested in code archeology, you can reduce the download time by limiting the clone [depth][git-clone-depth].
89
+
where `<username>` is your GitHub username. The repository has a large commit history, leading to slow download times. If you are not interested in code archeology, you can reduce the download time by limiting the clone [depth][git-clone-depth].
@@ -221,6 +228,65 @@ __Congratulations__! You are an official contributor to stdlib! Thank you for yo
221
228
222
229
## Notes
223
230
231
+
### GitHub
232
+
233
+
* When linking to specific lines of code in an issue or a pull request, hit the `y` key while viewing a file on GitHub. Doing so reloads the page with a URL that includes the specific version of the file you are viewing. This ensures that, when you refer to specific lines, these same lines can be easily viewed in the future, even if the content of the file changes.
234
+
* GitHub does not send notifications when you push a commit and update a [pull request][github-pull-request], so be sure to comment on the pull request thread to inform reviewers that you have made changes.
235
+
236
+
237
+
### Writing Tests
238
+
239
+
> By contributing tests to the project, you are agreeing to release it under the project [license][stdlib-license].
240
+
241
+
The project can __never__ have enough tests. To address areas lacking sufficient test coverage,
242
+
243
+
1. View the latest [coverage report][stdlib-code-coverage].
244
+
245
+
1. Browse the source files and find untested functionality highlighted in red.
246
+
247
+
1. Locate the package containing the source file in your forked repository.
248
+
249
+
1. Add tests to the package test file(s).
250
+
251
+
1. To run package tests,
252
+
253
+
```bash
254
+
$ make TESTS_FILTER=.*/<pattern>/.*test
255
+
```
256
+
257
+
where `<pattern>` is a pattern matching a particular path. For example, to test the base math `sin` package
258
+
259
+
```bash
260
+
$ make TESTS_FILTER=.*/math/base/special/sin/.*
261
+
```
262
+
263
+
where the pattern `.*/math/base/special/sin/.*` matches any test file whose absolute path contains `math/base/special/sin`.
264
+
265
+
1. To generate a test coverage report,
266
+
267
+
```bash
268
+
$ make TESTS_FILTER=.*/<pattern>/.* test-cov
269
+
$ make view-cov
270
+
```
271
+
272
+
which opens the coverage report in your default web browser.
273
+
274
+
1. Submit the test as a [pull request][github-pull-request].
275
+
276
+
277
+
### Writing Documentation
278
+
279
+
> By contributing documentation to the project, you are agreeing to release it under the project [license][stdlib-license].
280
+
281
+
Project documentation is localized within each package. Similar to code, you should modify documentation using [git][git]. Provided you have followed the [development guide][stdlib-development] and enabled git hooks,
282
+
283
+
```bash
284
+
$ make init
285
+
```
286
+
287
+
modified Markdown files are automatically linted prior to each commit. Any changes to documentation files should be free of lint errors. If a [pull request][github-pull-request] includes lint errors, the pull request will __not__ be accepted.
288
+
289
+
224
290
### Continuous Integration
225
291
226
292
Opening a [pull request][github-pull-request] automatically triggers a continuous integration build. Each pull request update queues an additional build. If a pull request has more than one build queued, only the most recent build in the queue is run.
@@ -247,15 +313,19 @@ Phew. While the above may be a lot to remember, even for what seem like minor ch
0 commit comments