gatsby-source-greenhouse-job-board/BREAKING_CHANGES.md

Gatsby source plugin for pulling offices, departments, and jobs into Gatsby from the Greenhouse Job Board API. It creates links between offices, departments, and jobs so they can be queried in Gatsby using GraphQL.

# Breaking Changes in v2.0.0

This document outlines the breaking changes introduced in version 2.0.0 of `gatsby-source-greenhouse-job-board`.

## ⚠️ Critical Breaking Changes

### 1. **Gatsby Version Requirement** (BREAKING)

**What changed:**
- Plugin now requires **Gatsby 5.0.0 or higher**
- Support for Gatsby 2, 3, and 4 has been removed

**Impact:**
- **Users on Gatsby 2, 3, or 4 must upgrade to Gatsby 5+**
- This aligns with modern Gatsby conventions and Node.js 18+ requirement

**Migration:**
- Upgrade Gatsby to version 5.0.0 or higher:
  ```bash
  npm install gatsby@^5.0.0
  ```
- Review Gatsby's [migration guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v4-to-v5/) for any breaking changes in your site

### 2. **Node.js Version Requirement** (BREAKING)

**What changed:**
- Minimum Node.js version increased from `>=14.15.0` to `>=18.0.0`
- This is required because we now use native `fetch` API (available in Node 18+)

**Impact:**
- **Users on Node.js 14, 15, 16, or 17 will need to upgrade to Node 18+**
- This aligns with Gatsby 5's requirement of Node 18+

**Migration:**
- Upgrade Node.js to version 18.0.0 or higher
- Use a Node version manager like `nvm`:
  ```bash
  nvm install 18
  nvm use 18
  ```

### 3. **Removed Axios Dependency** (NON-BREAKING)

**What changed:**
- Removed `axios` dependency
- Now uses native JavaScript `fetch` API

**Impact:**
- No functional changes - API calls work the same way
- Smaller bundle size (one less dependency)
- Better performance (native API)

**Migration:**
- No code changes needed
- If you were extending the plugin and importing axios, update to use `fetch` instead

### 4. **Node ID Format Change** (POTENTIALLY BREAKING)

**What changed:**
- Removed dependency on `gatsby-node-helpers` 
- Now uses Gatsby's native `createNodeId` API directly

**Impact:**
- **Node IDs may be different** between v1.x and v2.0.0
- If your site has hardcoded node ID references, GraphQL queries using node IDs, or programmatic node lookups, these may break
- GraphQL queries that reference nodes by ID will need to be updated

**Old format (gatsby-node-helpers):**
```javascript
generateNodeId('Job', job.id)  // Internal format may differ
```

**New format:**
```javascript
createNodeId(`GreenhouseJob-${job.id}`)  // Explicit format
```

**Migration:**
- If you have hardcoded node IDs, update them to match the new format
- Re-run `gatsby develop` or `gatsby build` to regenerate nodes with new IDs
- Update any GraphQL queries that filter by `id` if they were using the old format

### 5. **sourceNodes API Signature Change** (POTENTIALLY BREAKING)

**What changed:**
- Changed from old Gatsby 1.x API format to modern destructured format

**Old format:**
```javascript
exports.sourceNodes = async (gatsby, pluginOptions) => {
  const { actions } = gatsby
  // ...
}
```

**New format:**
```javascript
exports.sourceNodes = async ({ actions, createNodeId, reporter }, pluginOptions) => {
  // ...
}
```

**Impact:**
- This change aligns with Gatsby 2+ conventions
- If you were using Gatsby 1.x, this plugin would not have worked anyway
- **No action needed** if you're on Gatsby 2+ (which is required per peerDependencies)

### 6. **Error Handling Behavior Change**

**What changed:**
- Replaced `process.exit(1)` with `reporter.panic()`
- Error messages now use Gatsby's reporter API

**Impact:**
- Errors now properly integrate with Gatsby's error reporting system
- Build process will fail more gracefully
- Error messages may appear in a different format

**Migration:**
- No code changes needed, but be aware that error handling behavior is slightly different
- Errors will now show in Gatsby's standard error format

## ⚠️ Minor Breaking Changes

### 7. **Filter Response Handling**

**What changed:**
- Added `|| []` fallbacks when filtering responses

**Old code:**
```javascript
offices = filterResponseForIds(offices)  // Could return undefined
```

**New code:**
```javascript
offices = filterResponseForIds(offices) || []  // Always returns array
```

**Impact:**
- If your code relied on `undefined` being returned, this may cause issues
- Generally safer, but could affect edge cases

**Migration:**
- Review any code that checks for `undefined` from filtered responses
- Update to check for empty arrays instead

### 8. **Removed Dependencies**

**What changed:**
- Removed `gatsby-node-helpers` (replaced with Gatsby's native `createNodeId` API)
- Updated `chalk` from v2.4.2 to v4.1.2 (to match Gatsby's version)

**Impact:**
- `gatsby-node-helpers` is no longer available if you were importing it
- `chalk` is still included but at a newer version to match Gatsby
- This should not affect normal plugin usage

**Migration:**
- No action needed for normal plugin usage
- If you were extending the plugin and importing `gatsby-node-helpers`, update to use Gatsby's native APIs
- If you were importing `chalk`, ensure your code is compatible with v4.1.2

## ✅ Non-Breaking Improvements

These changes should not break existing functionality:

- Replaced `axios` with native `fetch` API (smaller bundle, better performance)
- Improved error messages with more context
- Better async/await error handling
- Updated Babel and build tools to match Gatsby's versions
- Modernized code to use Gatsby's native APIs

## 🔍 How to Verify Compatibility

1. **Test your GraphQL queries:**
   ```bash
   gatsby develop
   # Visit http://localhost:8000/___graphql
   # Verify all queries still work
   ```

2. **Check for hardcoded node IDs:**
   - Search your codebase for node IDs that might be hardcoded
   - Update any that reference Greenhouse nodes

3. **Review error handling:**
   - Test error scenarios (invalid boardToken, network failures)
   - Verify error messages are acceptable

## 📝 Recommendations

1. **Clear Gatsby cache after upgrading:**
   ```bash
   gatsby clean
   gatsby develop
   ```

2. **Test in a staging environment first**

3. **Update any custom code that references node IDs**

4. **Review GraphQL queries** to ensure they still work correctly

## 🆘 Need Help?

If you encounter issues after upgrading, please:
1. Clear your `.cache` and `public` directories
2. Check the error messages (they should be more informative now)
3. Verify your `boardToken` is correct
4. Open an issue on GitHub with details about your Gatsby version and error messages