# 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