diff --git a/docs/contributing/FAQ.md b/docs/contributing/FAQ.md new file mode 100644 index 00000000000..388137c0bac --- /dev/null +++ b/docs/contributing/FAQ.md @@ -0,0 +1,391 @@ + + +# Contributing FAQs + +> Frequently Asked Questions (FAQs) by First-Time Contributors to stdlib. + +- [Introduction](#intro) +- [As a first-time contributor to stdlib, where should I start?](#first-time-contributor) +- [How can I set up my development environment to contribute to stdlib?](#setup-dev-environment) +- [How can I install cppcheck?](#install-cppcheck) +- [I am seeing different return values in the JavaScript and C implementation for the same implementation.](#js-vs-c-return-values) +- [What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length?](#markdown-heading-length) +- [I have opened a pull request, where can I seek feedback?](#pr-feedback) +- [I need to generate fixtures for my tests. How can I do that, and what are the best references for inspiration?](#generate-fixtures) +- [I am facing a `Shadowed declaration` linting error in my C files, how can I fix it?](#shadowed-declaration) +- [I am facing a `Uninitialized variable` linting error in my C files, how can I fix it?](#uninitialized-variable) +- [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) +- [When should I use decimals in examples, benchmarks, and documentation, and when should I avoid them?](#decimal-usage) +- [How should I name my pull request?](#pr-naming) +- [How do I call the stdlib bot on my PR?](#stdlib-bot) +- [Frequently used `make` commands](#freq-make-commands) +- [Other Links](#other-links) + + + + + +## Introduction + +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. + + + +## As a first-time contributor to stdlib, where should I start? + +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. + + + +## How can I set up my development environment to contribute to stdlib? + +There are primarily two options for setting up your development environment to contribute to stdlib: + +1. [Manually setting up the development environment][manual-setup] +2. [Setting up the dev container][devcontainer-setup] + +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]. + +TODO: Modify the dev container setup link to the exact file link once it is merged. + + + +## How can I install cppcheck? + +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. + +```bash +$ make deps-install-cppcheck +``` + +For more installation commands, visit this [link][install-link]. + + + +## I am seeing different return values in the JavaScript and C implementation for the same implementation. + +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: + +```sh +CFLAGS="-ffp-contract=off" make install-node-addons NODE_ADDONS_PATTERN="math/base/special/foo" +``` + +Then, run the tests: + +```sh +make test TESTS_FILTER=".*/math/base/special/foo/.*" +``` + +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. + +- [Reference Discussion][ref-discussion] +- [Reference Comment][ref-comment] + + + +## What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length? + +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: + +```markdown + +``` + +TODO: Can we add a reference PR link? + + + +## I have opened a pull request, where can I seek feedback? + +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]! + + + +## I need to generate fixtures for my tests. How can I do that, and what are the best references for inspiration? + +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]. + + + +## I am facing a `Shadowed declaration` linting error in my C files, how can I fix it? + +```bash +STDLIB_MATH_BASE_NAPI_MODULE_FF_F( stdlib_base_gcdf ) ^ +/home/runner/work/stdlib/stdlib/lib/node_modules/@stdlib/math/base/special/gcdf/include/stdlib/math/base/special/gcdf.h:32:7: +note: Shadowed declaration float stdlib_base_gcdf( const float a, const float b ); +``` + +You can suppress that warning by adding a `// cppcheck-suppress shadowFunction` comment above the function. For example: + +```c +// cppcheck-suppress shadowFunction +STDLIB_MATH_BASE_NAPI_MODULE_FF_F( stdlib_base_gcdf ) +``` + + + +## I am facing a `Uninitialized variable` linting error in my C files, how can I fix it? + +```bash +lib/node_modules/@stdlib/stats/base/dmeanvarpn/benchmark/c/benchmark.length.c:112:38: warning: Uninitialized variable: x [uninitvar] + stdlib_strided_dmeanvarpn( len, 1, x, 1, out, 1 ); + ^ +lib/node_modules/@stdlib/stats/base/dmeanvarpn/benchmark/c/benchmark.length.c:104:17: note: Assuming condition is false + for ( i = 0; i < len; i++ ) { + ^ +lib/node_modules/@stdlib/stats/base/dmeanvarpn/benchmark/c/benchmark.length.c:112:38: note: Uninitialized variable: x + stdlib_strided_dmeanvarpn( len, 1, x, 1, out, 1 ); +``` +You can suppress that warning by adding a `// cppcheck-suppress uninitvar` comment above the function. For example: + +```c +// cppcheck-suppress uninitvar +stdlib_strided_dmeanvarpn( len, 1, x, 1, out, 1 ); +``` + + + +## I have the required packages in the expected paths, but I am still encountering an error like this while compiling the native add-on. + +![image](https://github.com/user-attachments/assets/6cb40866-c33b-4878-ab20-126472a56b63) + +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: + +```json +{ + // Other sections above.... + + "confs": [ + { + "task": "build", + "src": [ + "./src/main.c" + ], + "include": [ + "./include" + ], + "libraries": [], + "libpath": [], + "dependencies": [ + "@stdlib/math/base/napi/unary", + "@stdlib/math/base/assert/is-nanf", + "@stdlib/constants/float32/pinf" + ] + }, + { + "task": "benchmark", + "src": [ + "./src/main.c" + ], + "include": [ + "./include" + ], + "libraries": [], + "libpath": [], + "dependencies": [ + "@stdlib/math/base/assert/is-nanf", + "@stdlib/constants/float32/pinf" + ] + }, + { + "task": "examples", + "src": [ + "./src/main.c" + ], + "include": [ + "./include" + ], + "libraries": [], + "libpath": [], + "dependencies": [ + "@stdlib/math/base/assert/is-nanf", + "@stdlib/constants/float32/pinf" + ] + } + ] +} +``` + +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. + + + +## When should I use decimals in examples, benchmarks, and documentation, and when should I avoid them? + +Decimals help us differentiate floating-point values from integers. For instance, in JavaScript, all numbers are treated as floating-point values, but it is still important to distinguish between integers and floating-point numbers for clarity. Consider the following C function: + +```c +double stdlib_strided_dnanvariancetk( const CBLAS_INT N, const double correction, const double *X, const CBLAS_INT strideX ); +``` + +When calling this function in JavaScript, we expect the following usage: + +```javascript +var dnanvariancetk = require( '@stdlib/stats/base/dnanvariancetk' ); +var Float64Array = require( '@stdlib/array/float64' ); + +var x = new Float64Array( [ 1.0, -2.0, NaN, 2.0 ] ); + +// Use decimals for floating-point values, not for integers. +var v = dnanvariancetk( 4, 1.0, x, 1 ); +``` + +Notice that we used `1.0` as the second argument because it is a double-precision floating-point number. However, we did not use a decimal point for the first and fourth arguments, as they represent integers. + + + +## How should I name my pull request? + +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. + +TODO: Can we add a link to the PR naming guidelines here? + + + +## How do I call the stdlib bot on my PR? + +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: + +- `/stdlib update-copyright-years` - Updates copyright header years. +- `/stdlib lint-autofix` - Auto-fixes lint errors. + +To see other available bot commands, comment `/stdlib help` on your PR. + + + +## Frequently used `make` commands + +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: + +### 1. Install all dependencies + +```bash +$ make install +``` + +### 2. Initialize development environment + +```bash +$ make init +``` + +### 3. Compile native addon + +```bash +$ make install-node-addons NODE_ADDONS_PATTERN="math/base/special/abs" +``` + +### 4. Generate Test Fixtures + +- **Julia** +```bash +$ make test-fixtures-julia TESTS_FIXTURES_FILTER=".*/path/to/package/.*" +``` + +- **Python** +```bash +$ make test-fixtures-python TESTS_FIXTURES_FILTER=".*/path/to/package/.*" +``` + +For more `make` commands, refer to the test fixtures [documentation][test-fixtures]. + +### 5. Run the tests + +```bash +$ make TESTS_FILTER=".*/math/base/special/abs/.*" test +``` + +### 6. Run examples + +```bash +$ make EXAMPLES_FILTER=".*/math/base/special/abs/.*" examples +``` + +For more `make` commands, refer to the [documentation][examples] on running examples. + +### 7. Run benchmarks + +```bash +$ make BENCHMARKS_FILTER=".*/math/base/special/abs/.*" benchmark +``` + +For more `make` commands, refer to the [documentation][benchmark] on running benchmarks. + + + +## Other Links: + +- [Style Guide][style-guide] +- [Other make commands][make-commands] + + + + diff --git a/docs/contributing/img/close_terminal_prompt.png b/docs/contributing/img/close_terminal_prompt.png new file mode 100644 index 00000000000..f5e8a495f90 Binary files /dev/null and b/docs/contributing/img/close_terminal_prompt.png differ diff --git a/docs/contributing/img/close_terminal_prompt_end.png b/docs/contributing/img/close_terminal_prompt_end.png new file mode 100644 index 00000000000..0c2380d3a19 Binary files /dev/null and b/docs/contributing/img/close_terminal_prompt_end.png differ diff --git a/docs/contributing/img/electron_install_dev_container.png b/docs/contributing/img/electron_install_dev_container.png new file mode 100644 index 00000000000..3c7272afbd4 Binary files /dev/null and b/docs/contributing/img/electron_install_dev_container.png differ diff --git a/docs/contributing/img/post_create_script_start.png b/docs/contributing/img/post_create_script_start.png new file mode 100644 index 00000000000..18a453a112b Binary files /dev/null and b/docs/contributing/img/post_create_script_start.png differ diff --git a/docs/contributing/img/vscode_dev_container_prompt.png b/docs/contributing/img/vscode_dev_container_prompt.png new file mode 100644 index 00000000000..e6e9f5bbf00 Binary files /dev/null and b/docs/contributing/img/vscode_dev_container_prompt.png differ diff --git a/docs/contributing/img/welcome_to_codespaces_terminal.png b/docs/contributing/img/welcome_to_codespaces_terminal.png new file mode 100644 index 00000000000..c55d57b7b7b Binary files /dev/null and b/docs/contributing/img/welcome_to_codespaces_terminal.png differ diff --git a/docs/contributing/setting_up_a_devcontainer.md b/docs/contributing/setting_up_a_devcontainer.md new file mode 100644 index 00000000000..3287d2d6df4 --- /dev/null +++ b/docs/contributing/setting_up_a_devcontainer.md @@ -0,0 +1,130 @@ + + +# Devcontainer Setup + +> Step-by-step tutorial on how to set up a stdlib development environment in a dev container. + +## Introduction + +We appreciate your interest in contributing to stdlib! Below, we've provided a step-by-step tutorial on how to set up the project locally on your device using a dev container. + +Dev containers, are Docker containers that are specifically configured to provide a fully featured development environment with the right tooling, extensions, linting and formatting. They allow you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. + +The stdlib repository includes a preconfigured dev container, making it the easiest way to set up your development environment. It ensures proper linting, EditorConfig, and tooling are configured right from the start. + +**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]. + +### Prerequisites + +Setting up the stdlib dev container **requires** the following prerequisites: + +- [Git][git]: Version control +- [Docker][docker]: Containerization +- [VS Code][vscode]: Preferred IDE + +### Download + +To acquire the source code, first navigate to the parent directory where you want to place the project’s [Git][git] repository. + + + +```bash +$ cd /path/to/parent/destination/directory +``` + +Next, clone the repository. + + + +```bash +$ git clone https://github.com/stdlib-js/stdlib.git +``` + +If you are wanting to contribute to stdlib, first [fork][github-fork] the repository and amend the previous command. + + + +```bash +$ git clone https://github.com//stdlib.git +``` + +Open the repository in VS Code. + +```bash +$ cd stdlib && code . +``` + +When prompted, open the repository in the dev container. + + +
+ Prompt by VS Code to reopen the repository in a devcontainer. +
+
+ +Please be patient, as the post-create script may take some time to install all the required languages and dependencies. + +
+ Start of the post-create script in a terminal. +
+
+ +Close the terminal and wait for other dependencies to install. + +
+ Prompt to close the terminal and wait for other dependencies to install. +
+
+ +
+ Terminal window showing the progress of downloading Electron while configuring a Dev Container. +
+
+ +Close the terminal after the installation is completed. + +
+ Terminal window showing completion of the post-create script and prompting the user to close it. +
+
+ +If you see this when you open the terminal, then the dev container installation was successful! + +
+ Terminal window with a welcome message by GitHub Codespaces after it was successfully installed. +
+
+ + + +