Contributing
The agent is developed in the open at github.com/newrelic/node-newrelic under the Apache-2.0 license. This page summarizes how to set up a development environment, run the test suites, and get a pull request merged. The authoritative rules are in CONTRIBUTING.md.
Before You Start
- For a new feature or a complex change, open a GitHub issue first to discuss it with the maintainers.
- Pull requests are only accepted for agent version v6.11.0 or later.
- You must sign New Relic's Contributor License Agreement (a click-through through CLA-Assistant on your first PR).
- Third-party production dependencies are added reluctantly; be ready to justify one.
- Instrumentation has to work across a wide range of versions of each instrumented module. Code that looks overcomplicated may be that way for compatibility; read the comments and tests before "fixing" it.
Development Setup
- Fork the repository and clone your fork (the team itself works from forks too).
- Install a supported Node.js (
>=22.16.0) andnpm install. - Install Docker (the integration and versioned tests need databases and brokers).
- Optionally install the repository's Git hooks:
npm run addhook:precommit(setscore.hooksPathto.githooks).
documentation/developer-setup.md has a macOS checklist (Docker, nvm, postgresql for the pg-native tests, swapping LibreSSL for OpenSSL), and bin/macos-firewall.sh helps with firewall prompts during tests.
Running Tests
Tests use Node's built-in node:test runner, driven by borp with c8 for coverage. (CONTRIBUTING.md still mentions node-tap; the npm scripts are the current source of truth.)
| Command | What it runs |
|---|---|
npm run unit |
Unit tests: test/unit/**/*.test.{js,mjs}. No external services needed. |
npm run integration |
Integration tests in test/integration/ (installs sub-dependencies first). |
npm test |
Integration tests, then unit tests. |
npm run versioned |
Versioned tests in test/versioned/: each instrumented module tested against many of its versions. |
npm run versioned:major |
Versioned tests against major versions only. |
npm run smoke |
Smoke tests in test/smoke/ (talk to a real New Relic account). |
npm run unit:scripts |
Tests for the scripts in bin/. |
npm run bench |
Benchmarks. |
Services
Integration and versioned tests need services such as Cassandra, Memcached, MongoDB, MySQL, Postgres, and Redis:
npm run services # start containers (bin/start-services.sh, docker-compose.yml)
npm run services:stop # docker compose down
If the services run elsewhere or on non-standard ports, point the tests at them with NR_NODE_TEST_<SERVICE>_HOST and NR_NODE_TEST_<SERVICE>_PORT, where <SERVICE> is the upper-case service name (for example NR_NODE_TEST_MYSQL_PORT).
Writing tests
All changes are expected to come with tests. A PR without tests can be submitted, but it will not be merged until tests are written. Performance optimizations that do not change behavior are the rare exception.
Code Style
ESLint enforces the style (eslint.config.js):
npm run lint
npm run lint:fix
Configuration Schema Changes
The configuration schema lives in lib/config/schemas/. After changing it, regenerate the compiled artifacts and commit them:
npm run generate:config-validator
This writes lib/config/schema.generated.js (the pre-compiled validator the agent loads at startup) and lib/config/schema.json (the fully rendered schema). A unit test fails CI if the committed artifacts are stale.
Commits and Pull Requests
Commit messages follow Conventional Commits: a type (build, chore, ci, docs, feat, fix, perf, refactor, revert, security, style, test), an optional scope, and an imperative description:
feat(instrumentation): add support for Prisma Client
PRs are merged with squash and merge, and the PR title becomes the commit message, so the title must follow the convention too. The changelog (NEWS.md) is generated from these messages.
API Documentation
The JSDoc API reference can be built locally:
npm run public-docs # public API docs (jsdoc-conf.jsonc)
npm run docs # full docs including private members (out/)
Internals
The documentation/ folder explains internals for contributors, including the transaction naming philosophy, feature flags, function wrapping, and module instrumentations.
Security Issues
Do not report vulnerabilities in public issues. The README asks that they be reported through New Relic's bug bounty program. Also scrub logs and diagnostic output of personal or proprietary data before posting them anywhere public.