> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Workflow

> Development workflow, pre-commit checks, and pull request process

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

## Development Workflow

<Steps>
  <Step title="Fork and clone">
    Fork the repository and clone your fork:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/userland-migrations.git
    cd userland-migrations
    ```
  </Step>

  <Step title="Create a branch">
    Create a feature branch for your changes:

    ```bash theme={null}
    git checkout -b feat/my-new-recipe
    ```
  </Step>

  <Step title="Make your changes">
    Develop your recipe following the [creating recipes guide](/contributing/creating-recipes).
  </Step>

  <Step title="Run pre-commit checks">
    Before committing, run the comprehensive check suite:

    ```bash theme={null}
    npm run pre-commit
    ```

    This command will:

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

    <Warning>
      Commit any changes made by automatic fixes before proceeding.
    </Warning>
  </Step>

  <Step title="Restore modified fixtures">
    Some integration tests modify fixture files. Restore them before committing:

    ```bash theme={null}
    git restore recipes/*/tests/
    ```
  </Step>

  <Step title="Commit your changes">
    Commit using [Conventional Commits](https://www.conventionalcommits.org/) format:

    ```bash theme={null}
    git add .
    git commit -m "feat(tmpdir-to-tmpdir): add migration for DEP0022"
    ```
  </Step>

  <Step title="Push and create PR">
    Push your branch and create a pull request:

    ```bash theme={null}
    git push origin feat/my-new-recipe
    ```
  </Step>
</Steps>

## Pre-Commit Checks

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

### 1. Linting with Auto-Fix

```bash theme={null}
npm run lint:fix
```

Uses [Biome](https://biomejs.dev/) to:

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

### 2. Type Checking

```bash theme={null}
npm run type-check
```

Runs TypeScript compiler across all workspaces to catch type errors.

### 3. Test Suite

```bash theme={null}
npm test
```

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

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

## Commit Message Format

We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 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

<CodeGroup>
  ```text New Recipe theme={null}
  feat(tmpdir-to-tmpdir): add migration for DEP0022

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

  ```text Bug Fix theme={null}
  fix(util-log): preserve spacing in multiple arguments

  Previously, multiple arguments were concatenated without proper
  spacing. Now correctly preserves spacing between arguments.
  ```

  ```text Documentation theme={null}
  docs(contributing): add testing best practices

  Adds section on test coverage and debugging failed tests.
  ```

  ```text Chore theme={null}
  chore(deps): update @codemod.com/jssg-types to 1.5.0

  Updates jssg types to latest version for better TypeScript support.
  ```
</CodeGroup>

## Pull Request Process

### Creating a Pull Request

<Steps>
  <Step title="Write a clear PR title">
    Use the same Conventional Commits format:

    ```
    feat(recipe-name): add migration for DEP0XXX
    ```
  </Step>

  <Step title="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

    ```markdown theme={null}
    ## 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
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="Address review feedback">
    Respond to reviewer comments and push additional commits as needed.

    <Warning>
      **Do NOT force-push** unless absolutely necessary. Force-pushing breaks the PR review process and causes delays.
    </Warning>
  </Step>
</Steps>

### PR Acceptance Criteria

For a pull request to be merged, it must:

<Accordion title="Receive 2 approvals">
  At least 2 reviewers with write access must approve the PR.
</Accordion>

<Accordion title="Pass all CI checks">
  All automated tests and checks must pass:

  * Linting
  * Type checking
  * Tests on all platforms
  * YAML validation
</Accordion>

<Accordion title="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)
</Accordion>

<Accordion title="No objections from reviewers">
  No reviewer with write access has objected to the changes.
</Accordion>

<Accordion title="Follow contribution guidelines">
  Changes follow all guidelines in this documentation:

  * Proper file structure
  * Complete test coverage
  * Conventional commit format
  * Documentation included
</Accordion>

## Git Best Practices

### Branch Naming

Use descriptive branch names with type prefixes:

```bash theme={null}
feat/tmpdir-migration
fix/util-log-spacing
docs/update-testing-guide
chore/update-dependencies
```

### Avoiding Force Push

<Warning>
  **Never force-push to your PR branch** unless absolutely necessary.
</Warning>

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:

```bash theme={null}
# 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:

```yaml theme={null}
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:

<AccordionGroup>
  <Accordion title="(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.
  </Accordion>

  <Accordion title="(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.
  </Accordion>

  <Accordion title="(c) Provided by others">
    The contribution was provided directly to you by someone who certified (a) or (b) and you have not modified it.
  </Accordion>

  <Accordion title="(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.
  </Accordion>
</AccordionGroup>

## Getting Help

If you need assistance:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/nodejs/userland-migrations/issues">
    Ask questions or report problems
  </Card>

  <Card title="Codemod Documentation" icon="book" href="https://docs.codemod.com">
    Learn more about the Codemod framework
  </Card>

  <Card title="Creating Recipes" icon="wand-magic-sparkles" href="/contributing/creating-recipes">
    Review the recipe creation guide
  </Card>

  <Card title="Testing Guide" icon="flask" href="/contributing/testing">
    Review testing best practices
  </Card>
</CardGroup>