chore(gatsby): deprecate createJob, setJob and endJob actions (#29767)

Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>

packages/gatsby/src/redux/__tests__/jobs.ts

@@ -1,10 +1,60 @@
 import { actions } from "../actions"
 import { jobsReducer } from "../reducers/jobs"
 import { IGatsbyState } from "../types"
+import reporter from "gatsby-cli/lib/reporter"
+
+jest.mock(`gatsby-cli/lib/reporter`, () => {
+  return {
+    warn: jest.fn(),
+  }
+})
+
+beforeEach(() => {
+  ;(reporter as any).warn.mockClear()
+})
 
 Date.now = jest.fn(() => 1482363367071)
 
 describe(`Job actions/reducer`, () => {
+  it(`displays deprecation warning for createJob`, () => {
+    actions.createJob({ id: `test job` })
+    actions.createJob({ id: `test job` }, { name: `gatsby-plugin-foo` })
+    expect(reporter.warn).toHaveBeenCalledTimes(2)
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "createJob" is deprecated. Please use "createJobV2" instead`
+    )
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "createJob" is deprecated. Please use "createJobV2" instead (called by gatsby-plugin-foo)`
+    )
+  })
+
+  it(`displays deprecation warning for endJob`, () => {
+    actions.endJob({ id: `test job` })
+    actions.endJob({ id: `test job` }, { name: `gatsby-plugin-foo` })
+    expect(reporter.warn).toHaveBeenCalledTimes(2)
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "endJob" is deprecated. Please use "createJobV2" instead`
+    )
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "endJob" is deprecated. Please use "createJobV2" instead (called by gatsby-plugin-foo)`
+    )
+  })
+
+  it(`displays deprecation warning for setJob`, () => {
+    actions.setJob({ id: `test job`, progress: 40 })
+    actions.setJob(
+      { id: `test job`, progress: 40 },
+      { name: `gatsby-plugin-foo` }
+    )
+    expect(reporter.warn).toHaveBeenCalledTimes(2)
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "setJob" is deprecated. Please use "createJobV2" instead`
+    )
+    expect(reporter.warn).toHaveBeenCalledWith(
+      `Action "setJob" is deprecated. Please use "createJobV2" instead (called by gatsby-plugin-foo)`
+    )
+  })
+
   it(`allows creating jobs`, () => {
     expect(actions.createJob({ id: `test job` })).toMatchSnapshot()
   })

packages/gatsby/src/redux/actions/public.js

@@ -70,6 +70,15 @@ const findChildren = initialChildren => {
   return children
 }
 
+const displayedWarnings = new Set()
+const warnOnce = (message, key) => {
+  let messageId = key ?? message
+  if (!displayedWarnings.has(messageId)) {
+    displayedWarnings.add(messageId)
+    report.warn(message)
+  }
+}
+
 import type { Plugin } from "./types"
 
 type Job = {
@@ -1122,6 +1131,8 @@ actions.setBabelPreset = (config: Object, plugin?: ?Plugin = null) => {
 }
 
 /**
+ * DEPRECATED. Use createJobV2 instead.
+ *
  * Create a "job". This is a long-running process that is generally
  * started as a side-effect to a GraphQL query.
  * [`gatsby-plugin-sharp`](/plugins/gatsby-plugin-sharp/) uses this for
@@ -1130,10 +1141,18 @@ actions.setBabelPreset = (config: Object, plugin?: ?Plugin = null) => {
  * Gatsby doesn't finish its process until all jobs are ended.
  * @param {Object} job A job object with at least an id set
  * @param {id} job.id The id of the job
+ * @deprecated Use "createJobV2" instead
  * @example
  * createJob({ id: `write file id: 123`, fileName: `something.jpeg` })
  */
 actions.createJob = (job: Job, plugin?: ?Plugin = null) => {
+  let msg = `Action "createJob" is deprecated. Please use "createJobV2" instead`
+
+  if (plugin?.name) {
+    msg = msg + ` (called by ${plugin.name})`
+  }
+  warnOnce(msg)
+
   return {
     type: `CREATE_JOB`,
     plugin,
@@ -1209,15 +1228,25 @@ actions.createJobV2 = (job: JobV2, plugin: Plugin) => (dispatch, getState) => {
 }
 
 /**
+ * DEPRECATED. Use createJobV2 instead.
+ *
  * Set (update) a "job". Sometimes on really long running jobs you want
  * to update the job as it continues.
  *
  * @param {Object} job A job object with at least an id set
  * @param {id} job.id The id of the job
+ * @deprecated Use "createJobV2" instead
  * @example
  * setJob({ id: `write file id: 123`, progress: 50 })
  */
 actions.setJob = (job: Job, plugin?: ?Plugin = null) => {
+  let msg = `Action "setJob" is deprecated. Please use "createJobV2" instead`
+
+  if (plugin?.name) {
+    msg = msg + ` (called by ${plugin.name})`
+  }
+  warnOnce(msg)
+
   return {
     type: `SET_JOB`,
     plugin,
@@ -1226,15 +1255,25 @@ actions.setJob = (job: Job, plugin?: ?Plugin = null) => {
 }
 
 /**
+ * DEPRECATED. Use createJobV2 instead.
+ *
  * End a "job".
  *
  * Gatsby doesn't finish its process until all jobs are ended.
  * @param {Object} job  A job object with at least an id set
  * @param {id} job.id The id of the job
+ * @deprecated Use "createJobV2" instead
  * @example
  * endJob({ id: `write file id: 123` })
  */
 actions.endJob = (job: Job, plugin?: ?Plugin = null) => {
+  let msg = `Action "endJob" is deprecated. Please use "createJobV2" instead`
+
+  if (plugin?.name) {
+    msg = msg + ` (called by ${plugin.name})`
+  }
+  warnOnce(msg)
+
   return {
     type: `END_JOB`,
     plugin,