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
@@ -20,58 +20,128 @@ limitations under the License.
20
20
21
21
# Contributing FAQs
22
22
23
-
> frequently asked questions by first time contributors of stdlib.
23
+
> Frequently Asked Questions (FAQs) by First-Time Contributors to stdlib
24
+
25
+
-[Introduction](#intro)
26
+
-[As a first-time contributor to stdlib, where should I start?](#first-time-contributor)
27
+
-[How can I set up my development environment to contribute to stdlib?](#setup-dev-environment)
28
+
-[How can I install cppcheck?](#install-cppcheck)
29
+
-[I am seeing different return values in the JavaScript and C implementation for the same implementation.](#js-vs-c-return-values)
30
+
-[What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length?](#markdown-heading-length)
31
+
-[I have opened a pull request, where can I seek feedback?](#pr-feedback)
32
+
-[I need to generate fixtures for my tests. How can I do that, and what are the best references for inspiration?](#generate-fixtures)
33
+
-[I am facing a `Shadowed declaration` linting error in my C files, how can I fix it?](#shadowed-declaration)
34
+
-[I am facing a `Uninitialized variable` linting error in my C files, how can I fix it?](#uninitialized-variable)
35
+
-[I have the required packages in the expected paths, but I am still encountering an error like this while compiling the native add-on.](#compilation-error)
36
+
-[How should I name my pull request?](#pr-naming)
37
+
-[How do I call the stdlib bot on my PR?](#stdlib-bot)
38
+
-[Frequently used `make` commands](#freq-make-commands)
39
+
-[Other Links](#other-links)
24
40
25
41
<!-- lint disable no-heading-punctuation -->
26
42
43
+
<aname="intro"></a>
44
+
27
45
## Introduction
28
46
29
-
We appreciate your interest in contributing to stdlib! Below, we’ve compiled answers to some frequently asked questions (FAQs) from first-time contributors. If you’re new to the project or encounter any challenges, this guide is a great place to begin.
47
+
We appreciate your interest in contributing to stdlib! Below, we’ve compiled answers to some frequently asked questions (FAQs) from first-time contributors. If you’re new to the project or encounter any challenges, this guide is a great place to start.
48
+
49
+
<aname="first-time-contributor"></a>
50
+
51
+
## As a first-time contributor to stdlib, where should I start?
52
+
53
+
We recommend first familiarizing yourself with the stdlib codebase by reading the [contributing][contributing-guide] and [development][development-guide] guides. Once comfortable, you can start by working on a [good first issue][good-first-issues], fixing a bug, or resolving a TODO in the source code.
54
+
55
+
<aname="setup-dev-environment"></a>
56
+
57
+
## How can I set up my development environment to contribute to stdlib?
58
+
59
+
There are primarily two options for setting up your development environment to contribute to stdlib:
60
+
61
+
1.[Manually setting up the development environment][manual-setup]
62
+
2.[Setting up the dev container][devcontainer-setup]
63
+
64
+
Note: The dev container does not yet support ARM64 architectures. For more information, or if you're interested in adding ARM64 support, you can visit this [issue][devcontainer-issue].
30
65
31
-
## How can I set up my dev environment to contribute to stdlib?
66
+
TODO: Modify the dev container setup link to the exact file link once it is merged.
32
67
33
-
<!--- TODO add some documentation and links for the docs on devcontainer and manual setup --->
68
+
<aname="install-cppcheck"></a>
34
69
35
70
## How can I install cppcheck?
36
71
37
-
We use `cppcheck` in our project to perform linting on C/C++ code, to install `cppcheck`as per our project conventions
72
+
We use `cppcheck` in our project to perform linting on C/C++ code. To install `cppcheck`according to our project conventions, follow the specified installation step.
38
73
39
74
```bash
40
75
$ make deps-install-cppcheck
41
76
```
42
77
78
+
For more installation commands, visit this [link][install-link].
79
+
80
+
<aname="js-vs-c-return-values"></a>
81
+
43
82
## I am seeing different return values in the JavaScript and C implementation for the same implementation.
44
83
45
-
First, verify that your implementation is actually the same and doesn't contain a bug. Second, check whether your compiler is performing certain optimizations which may affect accuracy. A common optimization is rearranging terms. To check, compile the add-on and disable the optimization. E.g., `CFLAGS="-ffp-contract=on" make install-node-addons NODE_ADDONS_PATTERN="math/base/special/foo"` . Then run the tests. If they succeed, adjust the tolerance and add a note to the C tests indicating that the tolerance is higher relative to the JS implementation due to compiler optimizations. If they fail, raise an issue with maintainers to get feedback.
84
+
First, verify that your implementation is truly the same and does not contain any bugs. Second, check whether your compiler is performing optimizations that may affect accuracy. A common optimization is rearranging terms. To check this, compile the add-on while disabling the optimization:
46
85
47
-
## What can I do if the Markdown linting on my commits is failing due to my headings exceeding the maximum permissible length?
86
+
```sh
87
+
CFLAGS="-ffp-contract=off" make install-node-addons NODE_ADDONS_PATTERN="math/base/special/foo"
88
+
```
48
89
49
-
Consider whether we can make the heading shorter by renaming variables (e.g., `strideX` to `sx`). Second, disable the lint rule at the top-level. E.g., `<!-- lint disable maximum-heading-length -->`.
90
+
Then, run the tests:
91
+
92
+
```sh
93
+
make test TESTS_FILTER=".*/math/base/special/foo/.*"
94
+
```
50
95
51
-
## I have opened a pull request to stdlib, where can I go to seek feedback on it?
96
+
If they pass, adjust the tolerance and add a note to the C tests indicating that the tolerance is higher compared to the JavaScript implementation due to compiler optimizations. If they fail, raise an issue with the maintainers to get feedback.
52
97
53
-
Consider joining our [Gitter channel][stdlib-gitter]! We are very proud to say that we have a very active community where people ask each other for help and others answer each other's questions. One of the maintainers will soon review your pull request and provide feedback. You can also discuss things during our [weekly office hours meeting][stdlib-office-hours]!
98
+
-[Reference Discussion][ref-discussion]
99
+
-[Reference Comment][ref-comment]
54
100
55
-
## I need to generate fixtures for my tests. How can I do that, and what are the best references to take inspiration from?
101
+
<aname="markdown-heading-length"></a>
102
+
103
+
## What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length?
104
+
105
+
Consider whether the heading can be shortened by renaming variables (e.g., changing `strideX` to `sx`). If shortening is not possible, disable the lint rule at the top level using:
106
+
107
+
```markdown
108
+
<!-- lint disable maximum-heading-length -->
109
+
```
56
110
57
-
Tests are a very important part of any standard library package. We take our goal of achieving 100% test coverage very seriously, and we expect your work to be backed by tests. Often, you may need to generate fixtures to test your implementation against an existing implementation from a reliable source. You can use Julia, R, Python, etc., to generate fixtures. To get an idea of how we do it, see these reference scripts for generating fixtures: [Example python fixture script][python fixtures], [Example julia fixture script][julia fixtures].
111
+
TODO: Can we add a reference PR link?
58
112
59
-
## I am facing a `Shadowed declaration` linting error in my C files, how to get rid of that?
113
+
<aname="pr-feedback"></a>
114
+
115
+
## I have opened a pull request, where can I seek feedback?
116
+
117
+
Consider joining our [Gitter channel][stdlib-gitter]! We are proud to have a very active community where members help each other by asking and answering questions. A maintainer will review your pull request soon and provide feedback. You can also discuss it during our [weekly office hours meeting][stdlib-office-hours]!
118
+
119
+
<aname="generate-fixtures"></a>
120
+
121
+
## I need to generate fixtures for my tests. How can I do that, and what are the best references for inspiration?
122
+
123
+
Tests are a crucial part of any standard library package. We take our goal of achieving 100% test coverage very seriously and expect your work to be backed by tests. Often, you may need to generate fixtures to validate your implementation against an existing reliable source. You can use Julia, R, Python, or other languages to generate fixtures. To see how we do this, refer to these example scripts: [Python fixture script][python-fixtures], [Julia fixture script][julia-fixtures].
124
+
125
+
<aname="shadowed-declaration"></a>
126
+
127
+
## I am facing a `Shadowed declaration` linting error in my C files, how can I fix it?
In packages revolving around C implementations, you need to have a `manifest.json` file which tells [node-gyp][node-gyp] what dependencies to include for specific tasks. you need to include only the required dependencies for compiling, benchmarking and running examples for eg:
169
+
In packages involving C implementations, you need a `manifest.json` file to inform [node-gyp][node-gyp] about the dependencies required for specific tasks. You should include only the necessary dependencies for compiling, benchmarking, and running examples. For example:
97
170
98
171
```json
99
172
{
100
-
"options": {
101
-
"task": "build"
102
-
},
103
-
"fields": [
104
-
{
105
-
"field": "src",
106
-
"resolve": true,
107
-
"relative": true
108
-
},
109
-
{
110
-
"field": "include",
111
-
"resolve": true,
112
-
"relative": true
113
-
},
114
-
{
115
-
"field": "libraries",
116
-
"resolve": false,
117
-
"relative": false
118
-
},
119
-
{
120
-
"field": "libpath",
121
-
"resolve": true,
122
-
"relative": false
123
-
}
124
-
],
173
+
// Other sections above....
174
+
125
175
"confs": [
126
176
{
127
177
"task": "build",
@@ -173,11 +223,32 @@ In packages revolving around C implementations, you need to have a `manifest.jso
173
223
}
174
224
```
175
225
176
-
This config specifies that we need to include `@stdlib/math/base/napi/unary`, `@stdlib/math/base/assert/is-nanf`, `@stdlib/constants/float32/pinf` for compiling the native addon and `@stdlib/math/base/assert/is-nanf`, `@stdlib/constants/float32/pinf` for running benchmarks and examples
226
+
This `config` specifies that we need to include `@stdlib/math/base/napi/unary`, `@stdlib/math/base/assert/is-nanf`, and `@stdlib/constants/float32/pinf` for compiling the native add-on, while `@stdlib/math/base/assert/is-nanf` and `@stdlib/constants/float32/pinf` are required for running benchmarks and examples.
227
+
228
+
<aname="pr-naming"></a>
229
+
230
+
## How should I name my pull request?
231
+
232
+
The best strategy is to go through other relevant PRs and follow their naming conventions. If not, use a concise and descriptive title that clearly conveys the purpose of your changes and follows the PR naming guidelines.
233
+
234
+
TODO: Can we add a link to the PR naming guidelines here?
235
+
236
+
<aname="stdlib-bot"></a>
237
+
238
+
## How do I call the stdlib bot on my PR?
239
+
240
+
Once you have created your PR, you can call the **stdlib-bot** to perform basic operations such as fixing lint errors, updating copyright years, or merging changes from the `develop` branch into your PR. Some commonly used commands:
241
+
242
+
-`/stdlib update-copyright-years` - Updates copyright header years.
243
+
-`/stdlib lint-autofix` - Auto-fixes lint errors.
244
+
245
+
To see other available bot commands, comment `/stdlib help` on your PR.
246
+
247
+
<aname="freq-make-commands"></a>
177
248
178
249
## Frequently used `make` commands
179
250
180
-
We use [`GNU Make`][make] as our development utility and task runner for things like generating fixtures, compiling native addons, running tests, examples, benchmarks etc. Some of the most frequently used make commands which you will need in your workflow are:
251
+
We use [`GNU Make`][make] as our development utility and task runner for tasks such as generating fixtures, compiling native add-ons, running tests, examples, and benchmarks. Some of the most frequently used `make` commands that you will need in your workflow are:
181
252
182
253
### 1. Install all dependencies
183
254
@@ -197,12 +268,20 @@ $ make init
197
268
$ make install-node-addons NODE_ADDONS_PATTERN="math/base/special/abs"
198
269
```
199
270
200
-
### 4. Generate Julia Fixtures
271
+
### 4. Generate Test Fixtures
201
272
273
+
-**Julia**
202
274
```bash
203
275
$ make test-fixtures-julia TESTS_FIXTURES_FILTER=".*/path/to/package/.*"
204
276
```
205
277
278
+
-**Python**
279
+
```bash
280
+
$ make test-fixtures-python TESTS_FIXTURES_FILTER=".*/path/to/package/.*"
281
+
```
282
+
283
+
For more `make` commands, refer to the test fixtures [documentation][test-fixtures].
284
+
206
285
### 5. Run the tests
207
286
208
287
```bash
@@ -215,12 +294,23 @@ $ make TESTS_FILTER=".*/math/base/special/abs/.*" test
215
294
$ make EXAMPLES_FILTER=".*/math/base/special/abs/.*" examples
216
295
```
217
296
297
+
For more `make` commands, refer to the [documentation][examples] on running examples.
298
+
218
299
### 7. Run benchmarks
219
300
220
301
```bash
221
302
$ make BENCHMARKS_FILTER=".*/math/base/special/abs/.*" benchmark
222
303
```
223
304
305
+
For more `make` commands, refer to the [documentation][benchmark] on running benchmarks.
306
+
307
+
<aname="other-links"></a>
308
+
309
+
## Other Links:
310
+
311
+
-[Style Guide][style-guide]
312
+
-[Other make commands][make-commands]
313
+
224
314
<sectionclass="links">
225
315
226
316
[git]: http://git-scm.com/
@@ -231,17 +321,45 @@ $ make BENCHMARKS_FILTER=".*/math/base/special/abs/.*" benchmark
0 commit comments