Development Workflow

Follow this workflow to contribute changes to Node.js Userland Migrations.

Fork and clone

Fork the repository and clone your fork:

git clone https://github.com/YOUR_USERNAME/userland-migrations.git
cd userland-migrations

Create a branch

Create a feature branch for your changes:

git checkout -b feat/my-new-recipe

Make your changes

Develop your recipe following the creating recipes guide.

Run pre-commit checks

Before committing, run the comprehensive check suite:

npm run pre-commit

This command will:

Fix formatting and safe linting issues automatically
Check TypeScript types across all workspaces
Run all tests

Commit any changes made by automatic fixes before proceeding.

Restore modified fixtures

Some integration tests modify fixture files. Restore them before committing:

git restore recipes/*/tests/

Commit your changes

Commit using Conventional Commits format:

git add .
git commit -m "feat(tmpdir-to-tmpdir): add migration for DEP0022"

Push and create PR

Push your branch and create a pull request:

git push origin feat/my-new-recipe

Pre-Commit Checks

The npm run pre-commit command is your safety net. It runs:

1. Linting with Auto-Fix

npm run lint:fix

Uses Biome to:

Fix formatting issues (indentation, spacing, etc.)
Apply safe automatic fixes for common issues
Report remaining linting errors

2. Type Checking

npm run type-check

Runs TypeScript compiler across all workspaces to catch type errors.

3. Test Suite

npm test

Executes all tests in all recipe workspaces using the jssg test runner.

All three checks must pass before you can commit. If any fail, fix the issues and run npm run pre-commit again.

Commit Message Format

We follow Conventional Commits for automatic changelog generation and semantic versioning.

Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Type	Description	Example
`feat`	New feature or recipe	`feat(tmpdir): add tmpDir to tmpdir migration`
`fix`	Bug fix	`fix(util-log): handle multiple arguments correctly`
`docs`	Documentation changes	`docs(readme): update usage examples`
`test`	Test additions or fixes	`test(crypto-fips): add edge case tests`
`chore`	Maintenance tasks	`chore(deps): update ast-grep to v0.41.0`
`refactor`	Code refactoring	`refactor(utils): simplify binding resolution`
`perf`	Performance improvements	`perf(import-assertions): optimize AST traversal`

Scope

The scope is typically the recipe name or affected area:

tmpdir-to-tmpdir
util-log
utils
ci
docs

Examples

feat(tmpdir-to-tmpdir): add migration for DEP0022

Transforms tmpDir() calls to tmpdir() following the Node.js
deprecation DEP0022.

Pull Request Process

Creating a Pull Request

Write a clear PR title

Use the same Conventional Commits format:

feat(recipe-name): add migration for DEP0XXX

Fill out the PR description

Include:

What changes were made
Why the changes are needed
Link to related issues or deprecation notices
Examples of code transformations

## Summary

Adds migration recipe for DEP0022, transforming `tmpDir()` to `tmpdir()`.

## Changes

- Created `recipes/tmpdir-to-tmpdir/` with transformation logic
- Added tests covering CommonJS and ESM imports
- Updated documentation

## Related

Closes #123
Ref: https://nodejs.org/api/deprecations.html#dep0022-ostmpdir

Link related issues

Use GitHub keywords to automatically link issues:

Closes #123 - Closes the issue when PR is merged
Fixes #123 - Same as Closes
Resolves #123 - Same as Closes
Ref #123 - References the issue without closing

Wait for CI checks

GitHub Actions will automatically run:

Linting and type checking
Tests on Ubuntu, macOS, and Windows
Tests on multiple Node.js versions (22+)

All checks must pass before merge.

Address review feedback

Respond to reviewer comments and push additional commits as needed.

Do NOT force-push unless absolutely necessary. Force-pushing breaks the PR review process and causes delays.

PR Acceptance Criteria

For a pull request to be merged, it must:

Receive 2 approvals

At least 2 reviewers with write access must approve the PR.

Pass all CI checks

All automated tests and checks must pass:

Linting
Type checking
Tests on all platforms
YAML validation

Be open for 48 hours

PRs must remain open for at least 48 hours to allow for review and discussion.Exceptions:

Hotfixes for critical bugs
Trivial corrections (typos, formatting)

No objections from reviewers

No reviewer with write access has objected to the changes.

Follow contribution guidelines

Changes follow all guidelines in this documentation:

Proper file structure
Complete test coverage
Conventional commit format
Documentation included

Git Best Practices

Branch Naming

Use descriptive branch names with type prefixes:

feat/tmpdir-migration
fix/util-log-spacing
docs/update-testing-guide
chore/update-dependencies

Avoiding Force Push

Never force-push to your PR branch unless absolutely necessary.

Force-pushing:

Breaks the PR review process
Loses review context and comments
Makes it difficult for reviewers to see what changed
Causes significant delays

The repository uses squash-merge, so a clean commit history is not required. Each PR becomes a single commit using the PR title.

Keeping Your Branch Updated

If the main branch has moved ahead:

# Fetch latest changes
git fetch upstream main

# Merge (preferred over rebase for PRs)
git merge upstream/main

# Push the merge
git push origin your-branch

CI/CD Pipeline

The project uses GitHub Actions for continuous integration.

Quality Assurance Workflow

Triggered on every push and pull request:

jobs:
  lint-and-types:
    - Run Biome linting
    - Check TypeScript types

  validate-yaml:
    - Validate all YAML files

  test:
    - Run jssg tests on Ubuntu, macOS, Windows

  legacy-tests:
    - Run legacy tests on Node.js 22+
    - Test on all platforms

Publish Workflow

Automatically publishes recipes to the Codemod Registry when:

Changes are merged to main
Changes affect recipe directories

Developer’s Certificate of Origin

By contributing, you certify that:

(a) Original work

The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file.

(b) Modified work

The contribution is based upon previous work that is covered under an appropriate open source license and you have the right to submit that work with modifications under the same open source license.

The contribution was provided directly to you by someone who certified (a) or (b) and you have not modified it.

(d) Public record

You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it) is maintained indefinitely.

Getting Help

If you need assistance:

GitHub Issues

Ask questions or report problems

Codemod Documentation

Learn more about the Codemod framework

Creating Recipes

Review the recipe creation guide

Testing Guide

Review testing best practices

Contributing

API Reference

Development Workflow