Versioning

Deploy new code while runs are in progress, and know exactly what each run does with it.

Runs can last days or months, so you’ll often deploy a new version of a workflow while some of its runs are still in progress. Nelkap has no versions to manage: a run in progress executes your new code on its next call. This page explains what that means for each kind of change, so you can change a workflow without surprises.

How runs match new code

On each call, your workflow runs from its first line, and each step looks for its saved result by type and name, in the order your code reaches it. So what matters is the name of each step, not where it sits in your code:

• A step that keeps its name returns its saved result, even if you moved it.
• A step with a new name runs as a new step, even where an old one used to be.
• A saved step your code no longer reaches is ignored.

A run executes the new code from its next call: after a sleep or a wait, or when Nelkap calls again after a deploy cut a call off.

Changes to runs in progress

Change	Effect on a run in progress
Change code after the point the run has reached.	Its next call runs the new code from there.
Change the code inside a step the run has saved.	None: the saved result comes back. The new code runs only in runs that haven’t reached the step.
Move a step and keep its name.	None: the step is matched by its name.
Add a step before the point the run has reached.	The step runs on the next call, since it has no saved result.
Rename a step the run has saved.	Its work is done again, under the new name.
Remove a step.	Its saved result is ignored.
Change a sleep’s duration, or a wait’s key.	Once the run reaches it again, it pauses a second time, with the new duration or key. A run paused on it keeps its original wake-up time or key until it wakes.
Remove one of several steps with the same name.	The steps after it shift: each one gets the saved result of the one before it.

Adding a step is often what you want, like an email that every run in progress should still send. When it isn’t, branch on a version.

Once runs exist, keep the names of their steps, the durations of their sleeps, and the keys of their waits as they are. Changing one makes the runs in progress do that work, or that pause, a second time.

Version branching

When a change must only apply to new runs, branch on a version saved in the run’s first step. Add the step when you first write the workflow, returning 1. When a change comes, return the next number and branch on it:

nelkap/workflows/onboard-user.ts

import {
  createProfile,
  sendWelcomeEmail,
  sendWelcomeSurvey,
} from '../../activities';
import { nelkap } from '../client';

export async function onboardUser(userId: string) {
  const version = await nelkap.step.run('version', () => 2);

  await nelkap.step.run('profile', () => createProfile(userId));

  // Runs from version 2 on send the survey.
  if (version >= 2) {
    await nelkap.step.run('survey', () =>
      sendWelcomeSurvey(userId),
    );
  }

  await nelkap.step.sleep('1 day');

  await nelkap.step.run('welcome', () =>
    sendWelcomeEmail(userId),
  );
}

Runs started earlier saved 1, so they keep the old path. New runs save 2 and take the new one.

Rename or remove a workflow

A workflow’s name is how Nelkap tells your app which code to run. Renaming a workflow counts as removing the old name and adding a new one. Removing a workflow cancels its runs that haven’t started yet, and those sleeping or waiting. See Add and remove workflows.

To retire a workflow without cutting its runs short:

1. Stop new runs

   Remove its events and its schedule, and stop starting it from your code.

2. Let the last runs end

   Keep it registered, and filter your runs by the workflow until none is in progress.

3. Remove it

   Remove it from registerWorkflows, and deploy.