Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (123 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

175 lines (123 loc) · 4.17 KB

Contributing to Auth0 Deploy CLI

Thank you for your interest in contributing! This guide will help you get started with contributing to the Auth0 Deploy CLI project.

Getting Started

Prerequisites

  • Node.js ≥20.18.1
  • Git with signed commits configured
  • Auth0 Development Tenant (for testing)

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/auth0-deploy-cli.git
cd auth0-deploy-cli
  3. Add upstream remote: 
    git remote add upstream https://github.com/auth0/auth0-deploy-cli.git

Development Setup

# Install dependencies
npm i

Development Workflow

Create Feature Branch

# Sync with upstream
git fetch upstream
git checkout master
git merge upstream/master

# Create feature branch
git checkout -b feature/your-feature-name

Development Commands

# Development with watch mode
npm run dev

# Run tests
npm test

# Run single test file
npx ts-mocha test/path/to/specific.test.ts

# Lint and format
npm run lint:fix
npm run format

# Check TypeScript compilation
npx tsc --noEmit

# Run CLI locally for testing
npm run build && node lib/index.js --help

Testing Requirements

Before submitting a PR, ensure all tests pass:

# Unit tests (required)
npm test

Testing Your Changes Locally

To test your changes with the actual CLI:

# Build the project
npm run build

# Run CLI commands locally
node lib/index.js --help
node lib/index.js export --help
node lib/index.js import --help

# Example: Test export command
node lib/index.js export -c config.json -f yaml -o ./local-export/

# Example: Test import command
node lib/index.js import -c config.json -i ./local-export/tenant.yaml

Running Individual Tests

To run a single test file or specific test:

# Run all tests in a file
npx ts-mocha --timeout=7500 -p tsconfig.json test/tools/auth0/handlers/actions.tests.js

# Run a specific test by name
npx ts-mocha --timeout=7500 -p tsconfig.json \
  test/tools/auth0/handlers/actions.tests.js \
  -g="should create action"

Code Standards

  • ESLint (Airbnb base configuration)
  • Prettier formatting (100 character line width)
  • Comprehensive test coverage for new functionality
  • JSDoc comments for public APIs

Pull Request Process

  1. Ensure your branch is up to date with upstream master
  2. Run all tests and ensure they pass
  3. Create PR against the master branch
  4. Fill out the PR template completely:
    • Clear description of changes
    • Link to related issues
    • Testing approach
    • Complete the checklist
  5. Address code review feedback
  6. Ensure CI checks pass

PR Requirements

  • ✅ All CI checks pass
  • ✅ Code review approved
  • ✅ Tests added/updated for new functionality
  • ✅ Documentation updated (if applicable)
  • ✅ No merge conflicts
  • ✅ Signed commits

Commits

All commits should be signed to enhance security, authorship, trust and compliance.

About commit signature verification

Versioning

Versioning is managed by npm. Npm versioning will execute scripts that uses kacl to manage the CHANGELOG.

Ensure that before running the versioning scripts below, the Unreleased changelog is updated.

Production Versioning

npm version patch --no-git-tag-version

Beta Versioning

npm version prerelease --preid beta --no-git-tag-version

Getting Help

Code of Conduct

This project follows Auth0's Code of Conduct. By participating, you agree to uphold this code.