Rename parallelism env var to BACKSTAGE_CLI_PARALLELISM

Renames from BACKSTAGE_CLI_BUILD_PARALLEL to the more general
BACKSTAGE_CLI_PARALLELISM. The old name is still supported but
logs a one-time deprecation warning.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/cli-node/src/parallel/parallel.test.ts

@@ -50,24 +50,51 @@ describe('parseParallelismOption', () => {
 });
 
 describe('getEnvironmentParallelism', () => {
+  afterEach(() => {
+    delete process.env.BACKSTAGE_CLI_PARALLELISM;
+    delete process.env.BACKSTAGE_CLI_BUILD_PARALLEL;
+  });
+
   it('reads the parallelism setting from the environment', () => {
-    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = '2';
+    process.env.BACKSTAGE_CLI_PARALLELISM = '2';
     expect(getEnvironmentParallelism()).toBe(2);
 
-    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = 'true';
+    process.env.BACKSTAGE_CLI_PARALLELISM = 'true';
     expect(getEnvironmentParallelism()).toBe(defaultParallelism);
 
-    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = 'false';
+    process.env.BACKSTAGE_CLI_PARALLELISM = 'false';
     expect(getEnvironmentParallelism()).toBe(1);
 
-    delete process.env.BACKSTAGE_CLI_BUILD_PARALLEL;
+    delete process.env.BACKSTAGE_CLI_PARALLELISM;
     expect(getEnvironmentParallelism()).toBe(defaultParallelism);
   });
+
+  it('supports the deprecated BACKSTAGE_CLI_BUILD_PARALLEL with a warning', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = '3';
+    expect(getEnvironmentParallelism()).toBe(3);
+    expect(warnSpy).toHaveBeenCalledWith(
+      'The BACKSTAGE_CLI_BUILD_PARALLEL environment variable is deprecated, use BACKSTAGE_CLI_PARALLELISM instead',
+    );
+
+    warnSpy.mockClear();
+    expect(getEnvironmentParallelism()).toBe(3);
+    expect(warnSpy).not.toHaveBeenCalled();
+
+    warnSpy.mockRestore();
+  });
+
+  it('prefers BACKSTAGE_CLI_PARALLELISM over the deprecated variable', () => {
+    process.env.BACKSTAGE_CLI_PARALLELISM = '5';
+    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = '3';
+    expect(getEnvironmentParallelism()).toBe(5);
+  });
 });
 
 describe('runParallelWorkers', () => {
   afterEach(() => {
-    delete process.env.BACKSTAGE_CLI_BUILD_PARALLEL;
+    delete process.env.BACKSTAGE_CLI_PARALLELISM;
   });
 
   it('executes work in parallel', async () => {
@@ -75,7 +102,7 @@ describe('runParallelWorkers', () => {
     const done = new Array<number>();
     const waiting = new Array<() => void>();
 
-    process.env.BACKSTAGE_CLI_BUILD_PARALLEL = '4';
+    process.env.BACKSTAGE_CLI_PARALLELISM = '4';
     const work = runParallelWorkers({
       items: [0, 1, 2, 3, 4],
       parallelismFactor: 0.5, // 2 at a time

packages/cli-node/src/parallel/parallel.ts

@@ -20,7 +20,8 @@ import { Worker } from 'node:worker_threads';
 
 const defaultParallelism = Math.ceil(os.cpus().length / 2);
 
-const PARALLEL_ENV_VAR = 'BACKSTAGE_CLI_BUILD_PARALLEL';
+const PARALLEL_ENV_VAR = 'BACKSTAGE_CLI_PARALLELISM';
+const DEPRECATED_PARALLEL_ENV_VAR = 'BACKSTAGE_CLI_BUILD_PARALLEL';
 
 export type ParallelismOption = boolean | string | number | null | undefined;
 
@@ -51,8 +52,22 @@ export function parseParallelismOption(parallel: ParallelismOption): number {
   );
 }
 
+let hasWarnedDeprecation = false;
+
 export function getEnvironmentParallelism() {
-  return parseParallelismOption(process.env[PARALLEL_ENV_VAR]);
+  if (process.env[PARALLEL_ENV_VAR] !== undefined) {
+    return parseParallelismOption(process.env[PARALLEL_ENV_VAR]);
+  }
+  if (process.env[DEPRECATED_PARALLEL_ENV_VAR] !== undefined) {
+    if (!hasWarnedDeprecation) {
+      hasWarnedDeprecation = true;
+      console.warn(
+        `The ${DEPRECATED_PARALLEL_ENV_VAR} environment variable is deprecated, use ${PARALLEL_ENV_VAR} instead`,
+      );
+    }
+    return parseParallelismOption(process.env[DEPRECATED_PARALLEL_ENV_VAR]);
+  }
+  return defaultParallelism;
 }
 
 /**