Skip to content

Latest commit

 

History

History
210 lines (135 loc) · 6.54 KB

CONTRIBUTING.md

File metadata and controls

210 lines (135 loc) · 6.54 KB

Contributing

Thanks for your interest in contributing to this SDK! This document provides guidelines for contributing to the project.

Getting Started

Prerequisites

  • Node.js 20 or higher
  • yarn package manager

Installation

Install the project dependencies:

yarn install

Building

Build the project:

yarn build

Testing

Run the test suite:

yarn test

Run specific test types:

  • yarn test:unit - Run unit tests
  • yarn test:wire - Run wire/integration tests

Linting and Formatting

Check code style:

yarn run lint
yarn run format:check

Fix code style issues:

yarn run lint:fix
yarn run format:fix

Or use the combined check command:

yarn run check:fix

About Generated Code

Important: Most files in this SDK are automatically generated by Fern from the API definition. Direct modifications to generated files will be overwritten the next time the SDK is generated.

Generated Files

The following directories contain generated code:

  • src/api/ - API client classes and types
  • src/serialization/ - Serialization/deserialization logic
  • Most TypeScript files in src/

How to Customize

If you need to customize the SDK, you have two options:

Option 1: Use .fernignore

For custom code that should persist across SDK regenerations:

  1. Create a .fernignore file in the project root
  2. Add file patterns for files you want to preserve (similar to .gitignore syntax)
  3. Add your custom code to those files

Files listed in .fernignore will not be overwritten when the SDK is regenerated.

For more information, see the Fern documentation on custom code.

Option 2: Contribute to the Generator

If you want to change how code is generated for all users of this SDK:

  1. The TypeScript SDK generator lives in the Fern repository
  2. Generator code is located at generators/typescript/sdk/
  3. Follow the Fern contributing guidelines
  4. Submit a pull request with your changes to the generator

This approach is best for:

  • Bug fixes in generated code
  • New features that would benefit all users
  • Improvements to code generation patterns

Making Changes

Workflow

  1. Create a new branch for your changes
  2. Make your modifications
  3. Run tests to ensure nothing breaks: yarn test
  4. Run linting and formatting: yarn run check:fix
  5. Build the project: yarn build
  6. Commit your changes with a clear commit message
  7. Push your branch and create a pull request

Commit Messages

Write clear, descriptive commit messages that explain what changed and why.

Code Style

This project uses automated code formatting and linting. Run yarn run check:fix before committing to ensure your code meets the project's style guidelines.

Questions or Issues?

If you have questions or run into issues:

  1. Check the Auth0 documentation
  2. Search existing GitHub issues
  3. Open a new issue if your question hasn't been addressed

For questions about the Fern code generator itself, see the Fern documentation or Fern repository.

Beta Track Releases

Applies only when working on the beta branch.

This SDK ships two tracks from one npm package (auth0):

  • Stable (master): EA/GA endpoints only. Released by a maintainer via a release/* branch.
  • Beta (beta): a superset of stable plus beta-only endpoints. Released automatically when a PR is merged into beta.

The beta branch is regenerated from the stable spec plus the beta-only spec files; it is never produced by merging master into beta. It receives one combined regeneration PR (stable + beta) as a single squash commit.

Versioning

Beta uses the next stable minor + -beta.N, derived from git tags:

Latest stable: v6.3.0  →  Next beta: v6.4.0-beta.0
                           Subsequent betas: v6.4.0-beta.1, v6.4.0-beta.2, ...
                           Once v6.4.0 ships: v6.5.0-beta.0

Because v6.4.0-beta.N sorts before v6.4.0 in semver, consumers running npm install auth0 will never receive a beta version unless they explicitly pin it:

# Stable (default)
npm install auth0

# Beta (explicit prerelease pin)
npm install auth0@beta
# or a specific version
npm install auth0@6.4.0-beta.0

When merging a beta regeneration PR

Squash and merge with a commit message that marks each group:

Regenerate SDK (stable + beta) (#<pr-number>)

<!-- BETA -->
- feat: add `Management.Sandbox` preview API (Beta)
<!-- /BETA -->

<!-- STABLE -->
- feat: add tenant security headers configuration
<!-- /STABLE -->
  • Beta-only changes go inside the BETA markers; stable-mirrored changes go inside the STABLE markers.
  • The <!-- ... --> markers are HTML comments and stay invisible in GitHub's rendered view.
  • Omitting a section renders a "No ... changes in this release." note; omitting both falls back to the raw commit subject. Always prefer the structured form.
  • Everything reaches beta through a PR. Never push directly to beta — a direct push will not trigger a release.

What happens automatically after a PR is merged into beta

  1. The npm-release-beta workflow computes the next vX.Y.0-beta.N from git tags.
  2. It aborts if that tag already exists (prevents overwriting a published release).
  3. It parses the <!-- BETA --> / <!-- STABLE --> sections from the squash commit message.
  4. It stamps .version, package.json, src/management/version.ts, and CHANGELOG.md on disk.
  5. It builds the package and publishes to npm with --tag beta --provenance.
  6. It creates a signed release commit via the GitHub API (shows as Verified, no GPG key required).
  7. It tags the commit and publishes a GitHub prerelease.

Do not hand-edit release files on beta

The npm-release-beta workflow owns .version, package.json (version field), src/management/version.ts, and CHANGELOG.md on the beta branch. Never manually bump these files on beta.

Hand-written code

Code outside of the Fern-generated directories is hand-written and is not regenerated on beta. A fix on master does not reach beta automatically, so hand-written changes must be PR'd to both master and beta.

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.