Owner tasks

An owner task is a story that is yours to do, such as a Jira issue with the owner label. Foreman never picks it, and a story that depends on it waits until you mark it done. This page is for whoever writes the backlog: how to mark a task as yours in each story source, how to write it so its card on Waiting on you is useful, and when Foreman reminds you about one that holds a story.

The dashboard’s Waiting on you card for it shows what you need, how long it takes, the steps and when it is done. It reads them from four headings in the Jira issue’s description or the markdown story file:

• “What you need”
• “Steps”
• “Effort” (or “Takes”)
• “Done when”

They can be at any heading level, and each list item (or paragraph) is one item. Everything else in the description is left out. With no “Steps” and no “What you need”, the card says “No steps written yet.” and links to the task, so you know what to add.

# ACME-7 · Make the QA sandbox

## What you need

- Admin access to the Acme production org
- A name for the sandbox

## Steps

1. Open Setup, then Sandboxes.
2. Create a Developer sandbox named after the release.
3. Share the login with the team.

## Takes

about 15 minutes

## Done when

The sandbox shows as Completed in the Sandboxes list.

How the card is built

The card reads the story’s brief: the Jira issue’s description and its last 10 comments, the Salesforce Case’s Description and comments, or the markdown story file. The rules it follows:

• A heading’s name is matched in lower case, with spaces collapsed, a trailing colon dropped and any * or _ around it removed, so ## Steps: and **Steps** both count. “Effort” and “Takes” are the same section.
• A section runs to the next heading of any level. When a name appears twice, the first wins.
• Headings inside a code fence (``` or ~~~) are ignored. Reading stops at the first “Comments” or “Progress notes” heading, since Foreman writes those last and their text comes from elsewhere.
• “What you need” and “Steps” are list items, numbered or bulleted; a continuation line is joined to its item. With no list, each paragraph is one item. “Takes” and “Done when” are joined into one line.
• A body that is one italic line, such as “Not given in the issue.” in a brief, counts as empty.
• Only the first 256 KB of the text is read, and a line over 500 characters is never a heading.

On the dashboard the card sits under Your tasks. While the details load it reads “Fetching the steps…”; with nothing to show it reads “No steps written yet. Add ## Steps and ## What you need to ACME-7’s description.” with an Open link to the issue, the Case or the file. Its one action is Mark done, which marks the story done with the note “Marked done from the dashboard.” and raises the shipped event, the same as foreman story done <id> --note <text>. Under the title the card says what the task holds: “Frees ACME-12 now. 2 stories wait on it.”, or “Frees nothing by itself: ACME-12 also waits on ACME-9.” when something else holds that story too.

A task whose own depends_on has an open blocker sits under Later instead, with “Can start after ACME-9”. foreman status shows the same under “Your tasks”, one line per task with what it frees and what it takes, and foreman story plan lists the open owner tasks. The ranking is on Waiting on you.

Owner tasks in story files

Each story source has its own way of marking a task as yours.

Markdown. stories.ownerTask holds up to two patterns: title, matched against the title, and id, matched against the id. By default a title that contains “(owner task)” (in any case) is an owner task. A project whose owner tasks have ids of their own sets, for example:

"stories": {
  "adapter": "markdown",
  "dir": "stories",
  "ownerTask": { "id": "^ACME-O\\d+", "title": "\\(owner task\\)|\\[owner\\]" }
}

"ownerTask": {} turns detection off, so no markdown story is ever an owner task. The rest of the block is on Story files.

Jira. An issue with the label in stories.ownerLabel (default foreman-owner) is an owner task. A follow-up issue Foreman creates copies its origin’s labels but drops that one, so a follow-up is never mistaken for your work. See Stories from Jira.

Salesforce. Set stories.ownerField and stories.ownerValue to a picklist or multi-select field and the value that means an owner task ("ownerField": "Type", "ownerValue": "Owner task"); in a multi-select, any one of the chosen values matches. With neither set, a Case whose Subject contains “(owner task)” is one. See Stories from Salesforce.

Whatever the source, the picker never offers an owner task, a story that lists one in its depends_on waits for it, and foreman story plan labels the wait “(owner task)”. When you finish the task, mark it done on Waiting on you or with foreman story done <id> --note <text>; the stories that waited on it are picked from the next tick, and a run on standby wakes up for them.

Do not confuse an owner task with a task Foreman asks of you while a story builds (a key, an account, a sign-off). Those are decisions on Waiting on you, made with foreman decide add --kind task; they are answered, not marked done. See Waiting on you.

Reminders for tasks that hold a story

A story carries no created time, so Foreman starts a clock when the supervisor first sees an owner task that holds a story back: one under Your tasks (not Later) with at least one story waiting on it. It looks again every 5 minutes and keeps what it saw in .foreman/state.json, so the clock outlives a restart.

When a task has held a story for more than watchdog.ownerTaskHours (default 24; a fraction such as 0.5 is fine), Foreman tells you once: one info event in the run’s log and one email through the project’s notifier, the owner-task kind. Its subject is “An owner task still holds ACME-12”, the headline “Your task is holding up ACME-12”, and the lead is the event’s sentence, “Owner task ACME-7 “Make the QA sandbox” has held ACME-12 for 2 days.“, followed by “Foreman tells you this once; the story starts by itself once the task is marked done.” The email ends with two things to do: do the task and press Mark done on Waiting on you (or run foreman story done <task id>), or, if the story no longer needs it, take the dependency off the story.

A task that stops holding anything is forgotten, so it starts a fresh clock if it holds a story again later. The email needs a notifier and features.notifications on; see Notifications. The setting goes in the watchdog block of foreman.config.json:

"watchdog": { "ownerTaskHours": 8 }

Separately, when the run reaches standby with things waiting on you, it emails you once with what waits and what an answer would start (“Standby: 3 follow-up proposals and 1 owner task wait on you; finishing ACME-7 starts ACME-12.”), and does not send it again while the text is the same. Both are listed on Notifications; the key is on foreman.config.json.