CONTRIBUTING.md

Contributing to OpenFeature JS Client

Thank you for your interest in contributing to the OpenFeature JS Client! This document provides guidelines for contributing to the project, with a focus on the release process.

Project Structure

This is a monorepo managed with Lerna that contains multiple packages:

• @datadog/flagging-core - Runtime-agnostic flag-evaluation logic
• @datadog/openfeature-browser - Browser-specific bindings for OpenFeature
• @datadog/openfeature-node-server - Node.js server bindings for OpenFeature

The project uses independent versioning, meaning each package can have its own version number. Internal dependencies (e.g., @datadog/flagging-core) are pinned to exact versions on release (via command.version.exact in lerna.json) to prevent version skew.

Development Setup

1. Install dependencies:

   yarn install

2. Build all packages:

   yarn build

3. Run tests:

   yarn test

4. Type checking:

   yarn typecheck

5. Linting:

   yarn lint
   yarn lint:fix  # Auto-fix issues

Manual React Native Example

Run yarn example:react-native to build and pack the local core package and prepare an isolated Expo app. The same command reuses a per-checkout cache directory outside the repository and reinstalls a fresh core tarball on every run. Stop Metro before refreshing, then follow the printed cd / npm start commands to launch Expo Go on an iOS/Android simulator or device. The app verifies evaluation on Hermes and supports exports-enabled, legacy CommonJS, and legacy ESM Metro modes.

See the manual app README for prerequisites, expected results, and how to rebuild after SDK changes. Unlike the automated yarn test:react-native-install smoke test, this runs the code in a native JS runtime, not Node.

Entrypoint Guardrails

The default @datadog/flagging-core and @datadog/openfeature-browser entrypoints are expected to stay optimized for precomputed configurations. Rules-based parsing and its Protobuf-ES dependency must remain behind the ./rules-based entrypoints.

For a new core subpath, add its source module and package.json.exports mapping, then run the normal core build. Compatibility manifests, declaration mappings, publish-file lists, bundles, and smoke-test imports are derived automatically. See Adding a public entry point. Commit the generated metadata; yarn check:entrypoints rejects drift before CI builds or packing.

Recurring checks keep these contracts visible:

• yarn test:build checks generated entrypoint metadata and tests the generator, including adding a second/nested export without bundler registration.

• yarn test:react-native-install discovers every packed JavaScript subpath and checks modern and legacy resolution in the Metro matrix.

• packages/core/test/entrypoint-boundaries.spec.ts walks runtime imports from the default core/browser source entrypoints and fails if they reach generated protobuf code, Protobuf-ES, or rules-only parser modules.

• yarn test:browser-install builds the packed browser smoke app and runs scripts/report-entrypoint-bundle-sizes.js. The report compares DatadogProvider (precomputed fetching) with DatadogCoreProvider plus fetchRulesConfiguration (local rules evaluation), using the same OpenFeature initialization, boolean evaluation, and context-change flow with telemetry disabled for both. Playwright supplies configuration responses outside the measured bundles. These are complete scenario JS sizes, including OpenFeature and the shared harness, not isolated SDK or decoder sizes. Additional parser/fetch-wrapper smoke scenarios remain part of the dependency checks, summarized as a pass/fail result rather than a size table. Tracking-hook sizes are reported separately. In GitHub Actions the report is also appended to the step summary, pull request CI updates a sticky comment with the same report, and the script fails if default/precomputed bundles contain protobuf markers or rules-based bundles lack them.

• yarn test:node-install builds independent Webpack production bundles from the installed tarballs for the Node provider, SSR helpers (fetch client rules and serialize), and both together. scripts/report-node-entrypoint-bundle-sizes.js reports raw/gzip JS sizes and the same-build cost of adding SSR helpers to the provider. It selects the ESM module export condition, bundles dependencies except Node built-ins, and checks Webpack module statistics to ensure that only SSR bundles include Protobuf runtime or generated schema modules. The bundled functions are tested with fixture responses; the fixtures are not bundled. OpenFeature and dd-trace are not included. These are bundler scenario sizes, not npm install sizes, unbundled Node import costs, payload sizes, latency, or a direct comparison with the browser scenarios. To regenerate the report after installation, run node scripts/report-node-entrypoint-bundle-sizes.js and node --test test-app-node/bundle.test.cjs.

The sticky PR comment combines browser and Node reports after package-install checks. If only one report was generated, it identifies the missing report. The comment is only created or updated when the PR changes a bundle-relevant path. The allowlist in scripts/comment-entrypoint-bundle-sizes.js covers packages/browser/**, packages/core/**, packages/node-server/**, test-app/**, test-app-node/**, scripts/build/**, scripts/lib/**, the package-install/report/webpack-runner scripts, root dependency and build configuration, .yarn/**, and .github/workflows/ci.yaml. Markdown files are excluded. The filter checks the full PR diff, including deletions and both paths of renames, and publishes conservatively if GitHub's 3,000-file listing limit is reached. Report generation, the CI summary, smoke tests, and dependency checks still run regardless of the changed paths. yarn test:build covers the reports, filter, and comment creation/update behavior with mocked GitHub responses.

Release Process

Prerequisites

• Ensure you're not on the main branch (releases should be done from feature branches)
• All tests must pass
• Code must be linted and type-checked
• Changes should be committed and pushed
• Proper GitHub secrets must be configured:
  • NPM_PUBLISH_TOKEN_FLAGGING_CORE - Token for publishing core package
  • NPM_PUBLISH_TOKEN - Token for publishing browser package

Build Modes

The project supports different build modes that affect how the SDK version is determined:

1. Development Mode (dev)

• Default mode when BUILD_MODE is not set
• SDK version is set to "dev"
• Used during development and testing

2. Release Mode (release)

• Used for public releases
• SDK version uses the version from the package's package.json
• This is the mode used for production releases

3. Canary Mode (canary)

• Used on staging and production Datadog web app
• SDK version format: {package-version}-{commit-sha}
• Example: 0.1.0-alpha.2-a1b2c3d4

Run builds through yarn build, yarn workspace <package-name> build, or from the package directory. The build scripts read package.json from their working directory; release and canary builds fail if the package version cannot be read. Development builds continue to use dev.

yarn test:build verifies package-specific version stamping and runs in regular CI.

The publishing job sets BUILD_MODE=release for all steps, including the prepack rebuilds triggered by packing and publishing. CI also runs the packed-browser smoke test in release mode and verifies that configuration requests report the installed package's version.

SDK Setups

The project also supports different SDK setups:

• npm (default) - For npm package distribution
• cdn - For CDN distribution

Creating a Release

All packages are published with the latest npm tag.

Step 1: Prepare for Release

1. Switch to a feature branch:

   # For independent releases (describe what's being released)
   git checkout -b release/node-server-1.3.0
   git checkout -b release/browser-and-node-server-1.3.0
   
   # For unified releases (all packages with same version)
   git checkout -b release/v1.2.3

Step 2: Pin Internal Dependencies

2. Ensure internal dependencies use exact versions:

   yarn node ./scripts/release/update-peer-dependency-versions.js

   This script reads each package's current version and updates internal dependencies (like @datadog/flagging-core) to use exact versions without the ^ prefix. This prevents version skew between packages.

   After running, verify the changes:

   git diff packages/*/package.json

   You should see changes like:

   -    "@datadog/flagging-core": "^1.2.1"
   +    "@datadog/flagging-core": "1.2.1"

Step 3: Version the Package(s)

3. Update the version using the CLI:

   For independent releases (recommended):

   yarn release

   This command:

   • Validates you're not on the main branch
   • Runs lerna version --exact
   • Prompts for version updates only for changed packages
   • Creates version commits and tags per package (e.g., @datadog/openfeature-node-server@1.3.0)
   • Pushes version tags to Github

   For unified releases (all packages with same version):

   yarn release:all

   This command:

   • Same as above, but uses --force-publish to prompt for all packages
   • Use this when you want to release all packages together with the same version

Step 4: Open and Merge the Release PR

4. Open a PR from your release branch and merge it with a merge commit — not a squash.

   yarn release pushes the version tag onto your branch commit. Squashing creates a new commit on main and orphans that tag, which breaks change detection on the next release (Lerna falls back to an old tag and prompts to version packages that never changed). A merge commit keeps the tag reachable.

Step 5: Publish via GitHub Release

Publishing is fully automated via GitHub workflows!

1. Create a GitHub Release:

   • Go to the GitHub repository
   • Click "Releases" → "Create a new release"
   • Set the tag to match your version:
     • Independent: @datadog/openfeature-node-server@1.3.0 (publishes only that package)
     • Unified: v1.2.1 (publishes all packages)
   • Add release notes describing your changes or use the Generate Release Notes button
   • Click "Publish release"

   For multiple independent releases: Create a separate GitHub release for each package tag (e.g., one for @datadog/openfeature-browser@1.3.0 and one for @datadog/openfeature-node-server@1.3.0).

2. Automated Publishing Workflow:

   The release.yaml workflow will automatically trigger and:

   Validation Phase:

   • Checks that the GitHub release tag matches the corresponding package version
   • Fails fast if validation doesn't pass

   Build and Publish Phase:

   • Installs dependencies with yarn install --immutable
   • Builds all packages in release mode (BUILD_MODE=release)
   • Creates package tarballs with yarn lerna run pack --stream

   Publishing Sequence:

   For independent releases (@datadog/pkg@x.y.z):

   • Publishes only the specified package
   • If publishing browser or node-server, waits for flagging-core to be available on npm first

   For unified releases (vX.Y.Z):

   1. Publishes @datadog/flagging-core first
   2. Waits for npm registry propagation (up to 5 minutes)
   3. Publishes @datadog/openfeature-browser
   4. Publishes @datadog/openfeature-node-server

Package-Specific Build Commands

Core Package (@datadog/flagging-core)

# Build all formats (CommonJS and ESM)
cd packages/core
yarn build

# Build CommonJS only
yarn build:cjs

# Build ESM only
yarn build:esm

# Create package tarball
yarn pack

Browser Package (@datadog/openfeature-browser)

# Build all formats (CommonJS, ESM, and bundle)
cd packages/browser
yarn build

# Build bundle for CDN
SDK_SETUP=cdn yarn build:bundle

# Build CommonJS only
yarn build:cjs

# Build ESM only
yarn build:esm

# Create package tarball
yarn pack

Environment Variables

• BUILD_MODE: Controls the SDK version format

  • dev (default) - Development version
  • release - Production release version
  • canary - Canary version with commit SHA

• SDK_SETUP: Controls the SDK setup type

  • npm (default) - For npm distribution
  • cdn - For CDN distribution

Version Management

Since this project uses independent versioning:

• Each package has its own version number (stored in its package.json)
• yarn release prompts for version updates only for changed packages (independent releases)
• yarn release:all prompts for all packages (unified releases)
• Internal dependencies are pinned to exact versions (configured via command.version.exact in lerna.json)
• Version commits and tags are created per package (e.g., @datadog/openfeature-node-server@1.3.0)

⚠️ Version policy for @datadog/flagging-core: Internal dependencies are pinned to exact versions (enforced by scripts/internal-deps-validate.sh), so our packages never pull a core update implicitly. From 2.0.0 onward, flagging-core follows normal semver — minor/patch for backward-compatible changes, major for breaking ones. Two rules still apply:

1. Do not publish new 1.x versions of flagging-core. Legacy consumers still on ^1.2.1 would pull them and risk version skew; the 2.0.0 major bump exists to cap those consumers below 2.x.
2. Bumping core does not reach dependents automatically. Because openfeature-browser and openfeature-node-server pin core exactly, you must update each dependent's pin and re-release it (see Step 2) for consumers to pick up the new core.

Automated Release Workflow Details

The GitHub Actions workflow (release.yaml) includes several safety measures:

1. Version Consistency Check:

   • Compares GitHub release tag with the corresponding package version
   • Ensures tags and package versions are synchronized

2. Dependency Coordination:

   • Core package is published first
   • Waits for npm registry propagation (up to 5 minutes)
   • Browser package gets updated core dependency automatically

3. Build Integrity:

   • Uses BUILD_MODE=release for production builds
   • Replaces build environment variables correctly
   • Creates both npm packages and CDN bundles

Testing Before Release

1. Run all tests:

   yarn test

2. Type checking:

   yarn typecheck

3. Linting:

   yarn lint

4. Build verification:

   yarn clean
   yarn build
   yarn build:bundle

5. Package creation test:

   yarn version  # Pins internal dependencies and creates package tarballs

Troubleshooting

Common Issues

1. Release from main branch:

   • Error: "please do not release from main branch"
   • Solution: Create a feature branch for releases

2. Version mismatch in GitHub workflow:

   • Error: "Release tag doesn't match lerna.json version"
   • Solution: Ensure the GitHub release tag exactly matches v{version} format where {version} is from lerna.json

3. Build environment issues:

   • Ensure BUILD_MODE and SDK_SETUP are set correctly
   • Check that all dependencies are installed

4. Version synchronization issues:

   • Run yarn node ./scripts/release/update-peer-dependency-versions.js to pin internal dependencies
   • Verify internal dependencies use exact versions (no ^ prefix)

5. GitHub workflow failures:

   • Check the Actions tab for detailed error logs
   • Ensure GitHub secrets are properly configured:
     • NPM_PUBLISH_TOKEN_FLAGGING_CORE for core package
     • NPM_PUBLISH_TOKEN for browser package
   • Verify the release tag matches the version in lerna.json

6. npm registry propagation delays:

   • The workflow waits up to 5 minutes for the core package to be available
   • If this fails, it may indicate npm registry issues
   • Check npm status page or try republishing manually

7. Webpack build issues:

   • Ensure all TypeScript configurations are valid
   • Check that webpack configurations in each package are correct
   • Verify all required dependencies are installed

Getting Help

• Check the README.md for basic project information
• Review the scripts in the scripts/ directory for implementation details
• Check the GitHub Actions tab for workflow status and logs
• Examine the scripts/cli script for available commands (release, release_all, version, typecheck, lint)
• Open an issue on GitHub for bugs or feature requests

Manual Publishing (Emergency Only)

If the automated workflow fails and you need to publish manually:

1. Build packages:

   BUILD_MODE=release yarn build
   yarn version

2. Publish core package:

   cd packages/core
   npm publish --tag latest

3. Wait for propagation, then publish remaining packages:

   cd packages/browser
   npm publish --tag latest
   cd ../node-server
   npm publish --tag latest

Third-Party Licenses

All third-party dependency licenses are tracked in LICENSE-3rdparty.csv. This file is auto-generated and must be kept up to date whenever dependencies change. CI will fail if it is stale.

When to update

Re-generate the file whenever you add, remove, or update a dependency in any package.json.

Prerequisites

Requirement	Details
Python 3.11.12	pyenv install 3.11.12 && pyenv local 3.11.12
Go 1.23+	Required by dd-license-attribution
dd-license-attribution	pip install dd-license-attribution (repo)
GITHUB_TOKEN	See below

For Datadog employees, see the internal dd-license-attribution guide.

Setting GITHUB_TOKEN

If you already use the GitHub CLI, the easiest option is:

export GITHUB_TOKEN=$(gh auth token)

Otherwise, create a fine-grained personal access token with read access to Contents and Metadata at https://github.com/settings/personal-access-tokens and export it:

export GITHUB_TOKEN="github_pat_..."

Generating / updating licenses

export GITHUB_TOKEN=$(gh auth token)
yarn licenses:generate

This overwrites LICENSE-3rdparty.csv with the latest data. Commit the result.

Validating licenses locally

yarn licenses:validate

This checks that every npm package in yarn.lock has a corresponding entry in the CSV. No external tools or tokens are needed — it runs in CI the same way. If it fails, run yarn licenses:generate and commit the result.

Code Style

• Use TypeScript for all new code
• Follow the existing code style and patterns
• Run yarn lint:fix before committing
• Ensure all tests pass before submitting changes

Commit Messages

Follow conventional commit format with gitmoji:

• ✨ feat: for new features
• 🐛 fix: for bug fixes
• 📝 docs: for documentation changes
• 🎨 style: for formatting changes
• ♻️ refactor: for code refactoring
• ✅ test: for test changes
• 👷 chore: for maintenance tasks

Example: ✨ feat(browser): add new flag evaluation method