diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 116b603947bc17eff0bbae82be09dde8596f4203..1641b1c997aca95fd002cb4d1839c894384d4ad5 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -10,6 +10,10 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * allow `checkout: true`, `create: always` combination on run config to be abbreviated as `checkout: always` (#37) +=== Changed + +* rename `on_failure` key on run config to `failure`; keep `on_failure` key as alias (#38) + === Fixed * look for file extension only on base call when resolving batch script on Windows (#36) diff --git a/docs/modules/ROOT/pages/configure-run.adoc b/docs/modules/ROOT/pages/configure-run.adoc index 4f5e3ef4b5d0ff9365be6dcd7cb47059061b25f0..8b45599d1ec4260513eaf857686bc598cdb5e764 100644 --- a/docs/modules/ROOT/pages/configure-run.adoc +++ b/docs/modules/ROOT/pages/configure-run.adoc @@ -89,7 +89,7 @@ Acceptable keys for the map value are listed in the table below. |Map or Array |Environment variables to set or unset in the context of the command. -|<> +|<> |throw |String enum (ignore, log, or throw) |How to handle a non-zero exit value of the command. @@ -128,7 +128,7 @@ run: Only a single command is supported. Multiple commands cannot be chained together using chaining operators (`;`, `&&`, `||`, etc.). If you need to run multiple commands, you need to specify them as separate entries in the value of the `run` key. -You can handle when happens if a command fails using the `on_failure` key. +You can handle when happens if a command fails using the `failure` key. === Quoting arguments @@ -230,15 +230,22 @@ run: command: command-to-run --config-dir ${{env.HOME}}/.config/config-for-command ---- -== on_failure key +== failure key -The `on_failure` key can be used to control what happens when the command fails. +The `failure` key can be used to control what happens when the command fails. A failed command is one that exits with a non-zero exit value. If the value is `ignore`, the failure is silently ignored. If the value is `log`, the failure is logged at the error level. -The level can be tuned by appending it as a property on the log keyword (e.g., `log.warn`). +The log level can be tuned by appending it as a property on the log keyword (e.g., `log.warn`). If the value is `throw` (default), the error bubbles, which causes the execution of Antora to immediately stop, just like any other fatal error. +[,yaml] +---- +run: + command: command-that-fails + failure: log.warn +---- + == env key The `env` key can be used to set (or unset) additional environment variables for the run command. diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js index 709f3597bf095db9163c50a5123834e36466496e..b36077dd2b955e710115f95a44cf06143b940c7c 100644 --- a/packages/collector-extension/lib/index.js +++ b/packages/collector-extension/lib/index.js @@ -99,7 +99,9 @@ module.exports.register = function ({ config: { createWorktrees = 'auto', keepWo command = `"${contextVars.env.NODE}" ${command}` } } - accum.push(Object.assign({}, run, { command: evaluate(contextVars, command), dir, env, local })) + command = evaluate(contextVars, command) + const failure = 'failure' in run ? run.failure : 'on_failure' in run ? run.on_failure : run.onFailure + accum.push(Object.assign({}, run, { command, dir, env, local, failure })) } return accum }, []), @@ -125,7 +127,7 @@ module.exports.register = function ({ config: { createWorktrees = 'auto', keepWo } for (const { clean: cleans, run: runs, scan: scans } of collectors) { for (const clean of cleans) await fsp.rm(clean.dir, { recursive: true, force: true }) - for (const { dir: cwd, command, local, shell, env, on_failure, onFailure = on_failure } of runs) { + for (const { dir: cwd, command, local, shell, env, failure } of runs) { try { await runCommand(command, { cwd, local, shell: !!shell, env, output: true, quiet }) } catch (err) { @@ -133,7 +135,7 @@ module.exports.register = function ({ config: { createWorktrees = 'auto', keepWo const qualifier = worktree ? ' ' : remote && worktree === false ? ` ` : '' const pathInfo = startPath ? ` | start path: ${startPath}` : '' err.message = err.message.replace(/$/m, ` in ${loc} (${reftype}: ${refname}${qualifier}${pathInfo})`) - const failureAction = typeof onFailure === 'string' ? onFailure : 'throw' + const failureAction = typeof failure === 'string' ? failure : 'throw' if (failureAction === 'throw') { throw Object.assign(err, { message: `(${PACKAGE_NAME}): ${err.message}` }) } else if (failureAction === 'log' || failureAction.startsWith('log.')) { diff --git a/packages/collector-extension/test/collector-extension-test.js b/packages/collector-extension/test/collector-extension-test.js index f79fc8996bf0a89c9bc51822230e7f0d98633b48..6581aaf353dbb1ed91318aa914210fdad12ca456 100644 --- a/packages/collector-extension/test/collector-extension-test.js +++ b/packages/collector-extension/test/collector-extension-test.js @@ -2025,11 +2025,11 @@ describe('collector extension', () => { }) it('should ignore error if command fails when on_failure is ignore', async () => { - const collectorConfig = { run: { command: 'no-such-command', on_failure: 'ignore' } } + const collectorConfig = { run: { command: 'no-such-command', failure: 'ignore' } } assert.doesNotThrow(await trapAsyncError(() => runScenario({ repoName: 'test-at-root', collectorConfig }))) }) - it('should log error if command fails when on_failure is log', async () => { + it('should log error if command fails when on_failure is log (on_failure is alias for failure)', async () => { const collectorConfig = { run: { command: 'no-such-command', on_failure: 'log' } } const expectedMessage = `Command not found: no-such-command in http://localhost:${gitServerPort}/test-at-root/.git (branch: main)` assert.doesNotThrow(await trapAsyncError(() => runScenario({ repoName: 'test-at-root', collectorConfig }))) @@ -2047,8 +2047,8 @@ describe('collector extension', () => { assert(err.message.includes(expectedMessage)) }) - it('should log at specified level if command fails when on_failure is log.warn', async () => { - const collectorConfig = { run: { command: 'no-such-command', on_failure: 'log.warn' } } + it('should log at specified level if command fails when failure is log.warn', async () => { + const collectorConfig = { run: { command: 'no-such-command', failure: 'log.warn' } } const expectedMessage = `Command not found: no-such-command in http://localhost:${gitServerPort}/test-at-root/.git (branch: main)` assert.doesNotThrow(await trapAsyncError(() => runScenario({ repoName: 'test-at-root', collectorConfig }))) assert.equal(messages.length, 1)