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

  1. Fork the repository and clone your fork (the team itself works from forks too).
  2. Install a supported Node.js (>=22.16.0) and npm install.
  3. Install Docker (the integration and versioned tests need databases and brokers).
  4. Optionally install the repository's Git hooks: npm run addhook:precommit (sets core.hooksPath to .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.

See Also