|
| 1 | +# Agent Guidance |
| 2 | + |
| 3 | +Non-discoverable operational guidance for Node.js development. |
| 4 | + |
| 5 | +## Non-discoverable commands |
| 6 | + |
| 7 | +### Linting |
| 8 | + |
| 9 | +- `tools/eslint/node_modules/eslint/bin/eslint.js` is the actual lint runner (not `make lint-js` which first builds it) |
| 10 | +- `make lint` runs: JS lint, C++ lint, addon docs lint, markdown lint, YAML lint |
| 11 | +- CI uses `make lint-js-ci` (different output format than regular `make lint-js`) |
| 12 | + |
| 13 | +### Testing |
| 14 | + |
| 15 | +- `make test` = `make test-only` + documentation build |
| 16 | +- `make test-only` = default tests without documentation build |
| 17 | +- `make test-tap` = TAP output format |
| 18 | +- `make test-only TAP=1` = subset of tests in TAP format |
| 19 | + |
| 20 | +### Test organization |
| 21 | + |
| 22 | +- `test/parallel/` = tests that can run in parallel (add new tests here when unsure) |
| 23 | +- `test/sequential/` = tests that must not run in parallel |
| 24 | +- `test/pummel/` = load tests, not run on CI |
| 25 | +- `test/internet/` = tests with real outbound connections, not run on CI |
| 26 | +- `test/known_issues/` = all tests expected to fail, run via `known_issues.status` |
| 27 | + |
| 28 | +## Landmines / do-not-touch areas |
| 29 | + |
| 30 | +### Dependencies |
| 31 | + |
| 32 | +- `deps/` and `tools/` contain bundled dependencies not part of Node.js proper |
| 33 | +- Do not send patches to Node.js for files in these directories |
| 34 | +- Send changes to their respective projects instead |
| 35 | + |
| 36 | +### Build artifacts |
| 37 | + |
| 38 | +- `out/` directory is generated (not tracked in git, but `.gitignore` has exceptions) |
| 39 | +- `node` is a symlink to `out/Release/node` |
| 40 | +- `config.gypi`, `config.status`, `config.mk`, `icu_config.gypi` are generated by `./configure` |
| 41 | + |
| 42 | +### Branch workflow |
| 43 | + |
| 44 | +- Only create branches in your GitHub fork (not `nodejs/node`) |
| 45 | +- `nodejs/node` branches are only for release lines |
| 46 | + |
| 47 | +## Task-specific constraints |
| 48 | + |
| 49 | +### Tests |
| 50 | + |
| 51 | +- Tests must `require('../common')` first (not just for helpers, but for: globals leak check, umask enforcement, auto-respawn with flags) |
| 52 | +- Test flags can be specified in comment: `// Flags: --expose-internals` |
| 53 | +- Use `port: 0` instead of arbitrary ports for parallel-safe tests |
| 54 | +- Use `common.mustCall()` to verify callbacks are invoked |
| 55 | +- Tests exit 0 on success, non-zero (or `process.exitCode`) on failure |
| 56 | + |
| 57 | +### Build system |
| 58 | + |
| 59 | +- `./configure` must run before `make` commands |
| 60 | +- `make -j4` is typical parallel build |
| 61 | +- Ninja build system available as faster alternative (`./configure --gyp-mode=ninja`) |
| 62 | + |
| 63 | +### Commit messages |
| 64 | + |
| 65 | +- First line: `<subsystem>: <description>` (lowercase, imperative verb) |
| 66 | +- Find subsystems via: `git log --oneline files/you/changed` |
| 67 | +- `Fixes:` and `Refs:` trailers auto-added from PR description when landing |
| 68 | +- Breaking changes need `semver-major` label + explanation |
| 69 | + |
| 70 | +### CI/CI workflows |
| 71 | + |
| 72 | +- `.github/workflows/test-linux.yml` is the main CI test workflow |
| 73 | +- `.github/workflows/linters.yml` runs lint checks |
| 74 | +- `test/root.status` defines test status (SLOW, SKIP, etc.) per platform |
| 75 | + |
| 76 | +## Development helpers |
| 77 | + |
| 78 | +### Speed up rebuilds |
| 79 | + |
| 80 | +- `make V=1` for verbose output |
| 81 | +- `--enable-coredll` loads JS from disk instead of embedding (faster rebuilds) |
| 82 | +- `ccache` can be used via `./configure --with-ccache` |
| 83 | + |
| 84 | +### Debug builds |
| 85 | + |
| 86 | +- `./configure --debug && make` for debug build |
| 87 | +- `make V=1` for build verbosity |
| 88 | + |
| 89 | +### Coverage |
| 90 | + |
| 91 | +- `make coverage` generates coverage reports |
| 92 | +- `COV_SKIP_TESTS` env var to skip specific tests |
0 commit comments