Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
196 lines (136 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

196 lines (136 loc) · 5.24 KB

Contributing

Development

This is a monorepo containing the Langfuse TypeScript/JavaScript SDK packages:

Getting Started

Prerequisites

  • Node.js 20+
  • pnpm (package manager)

Installing dependencies

pnpm install

Building packages

# Build all packages
pnpm build

# Build and watch for changes
pnpm build --watch

Testing

Integration tests

Integration tests run fully locally using a MockSpanExporter to verify SDK behavior without requiring external services.

# Run integration tests
pnpm test:integration

# Run integration tests in watch mode
pnpm test:integration:watch

End-to-end tests

End-to-end tests require a running Langfuse platform instance (dev server) to test the full integration flow.

Setup

  1. Start local Langfuse server
  2. Create testing project
  3. Set environment variables: LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY

Run

# Run E2E tests
pnpm test:e2e

Code Quality

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
pnpm format:check

# Type checking
pnpm typecheck

# Run all CI checks
pnpm ci

Publishing

This project uses lockstep versioning - all packages are released together with the same version number. Releases are managed using release-it with conventional commits and automated changelog generation.

Automated Releases via GitHub Actions (Recommended)

Releases are primarily handled through GitHub Actions with npm Trusted Publishing for secure, automated deployments.

To create a new release:

  1. Navigate to Actions → Release workflow
  2. Click Run workflow
  3. Select the version bump type:
    • patch - Bug fixes (4.4.4 → 4.4.5)
    • minor - New features (4.4.4 → 4.5.0)
    • major - Breaking changes (4.4.4 → 5.0.0)
    • prerelease - Alpha/beta/rc versions
  4. If prerelease, select type (alpha, beta, or rc)
  5. (Optional) Check Dry run to test without publishing
  6. Click Run workflow

The automated workflow will:

  • Verify release is triggered from main branch
  • Update versions in all package.json files across the monorepo
  • Generate a changelog based on conventional commits
  • Create a git commit and tag
  • Build all packages
  • Verify build artifacts and check for suspicious files
  • Publish to npm with provenance attestations via Trusted Publishing
  • Create a GitHub release with build artifacts
  • Send Slack notifications (#releases for success, #team-engineering for failures)

Security Features:

  • Branch verification (must run from main)
  • Lockfile integrity checks
  • Build artifact verification
  • npm provenance attestations (cryptographic proof of origin)
  • Concurrency control (one release at a time)
  • Rollback detection and notification

Prerequisites:

  • Write access to the repository
  • npm Trusted Publishing configured for @langfuse/* packages

Dry Run Mode:

To test the release process without actually publishing:

  • Check the "Dry run" option when triggering the workflow
  • The workflow will perform all steps except npm publish and git push
  • Useful for testing version bumps and verifying the release process

Manual Local Releases (Fallback)

If GitHub Actions are unavailable, you can release locally:

# Production release
pnpm release

# Pre-release versions
pnpm release:alpha  # Alpha release
pnpm release:beta   # Beta release
pnpm release:rc     # Release candidate

# Dry run (preview changes without publishing)
pnpm release:dry

Local release prerequisites:

  • npm authentication (npm login) with publish access
  • Clean working directory
  • On the main branch
  • Upstream remote configured
  • Git push access

Note: Local releases use the default .release-it.json configuration which includes npm publishing. For local testing without publishing, use the dry run command.

Pre-release Versions

Pre-release versions (alpha, beta, rc):

  • Are published with appropriate npm dist-tags
  • Won't be installed by default with npm install @langfuse/client
  • Must be explicitly installed: npm install @langfuse/client@alpha
  • Are tagged in git for full traceability
  • Generate pre-release entries in the changelog

Provenance Attestations

All packages published via GitHub Actions include npm provenance attestations, providing cryptographic proof that packages were built from this repository. Users can verify package authenticity with:

npm view @langfuse/client --json | jq .dist.attestations

Development Workflow

  1. Create a feature branch from main
  2. Make your changes
  3. Add tests for your changes
  4. Run pnpm ci to ensure all checks pass
  5. Create a pull request