StoryBoard/Vision

This document aims to provide a long-term vision for StoryBoard, to put our requirements and features in context. It will try to stay high-level and not make statements about implementation.

A task tracker

The main feature of StoryBoard is providing task tracking across multiple teams, multiple code repositories, or even multiple branches within those code repositories. You describe inter-related tasks as part of a overarching story. For example, imagine a vulnerability affecting Glance and Nova. This is the story. It has a task to fix the vulnerability in the Glance master branch, a task to fix the vulnerability in the Nova master branch, and a task for the Vulnerability Management team to potentially issue a security advisory. Investigation reveals that the Havana and Icehouse releases of Nova are affected, so we add a task to backport the fix to the stable/icehouse Nova branch, and another to backport the fix to stable/havana. All those tasks affect slightly different groups of people, but the story won't be solved until all those groups complete their work. StoryBoard helps tracking what tasks need to be done and which ones are already completed... ensuring that nothing falls through the cracks of our complex organization.

StoryBoard is also used to track work items for complex implementations. For example, imagine a feature that requires multiple steps to implement. You can express those steps as successive tasks in a single story. As those steps are marked completed, it's easy to evaluate progress in the implementation.

Using StoryBoard, it's easy for teams and individuals to organize their work, arbitrarily grouping sets of tasks as sprint objectives or personal goals. Integrated release goals (development milestone targets) are just the community-wide level expression of that.

Using StoryBoard, it's also easy to browse tasks for sets of projects that matter to you. The project (code repository) is not always the granularity that makes the most sense for browsing. For example, the infrastructure team generally looks at tasks at the openstack-infra/* level. The Oslo team generally looks at tasks at the openstack/oslo* level. The Storyboard team generally looks at tasks at the openstack-infra/storyboard* level. Some teams even want to track tasks that will not really result in a commit in a code repository (like security advisory publication).

Using StoryBoard, it is also easy to get to a list of security fixes, bugfixes and new features that were shipped in a given release. Those make great reference for downstream users of our software.

Relationship with gerrit

Gerrit is the code review system where individual code changes are uploaded and reviewed before merging. It doesn't show TODO or under development tasks, it only shows work that is ready for review and merging into a code repository. It also has limited support for discovering interrelated changes.

Gerrit is complementary to StoryBoard. It's where the merits of a specific changeset are discussed, and successive versions of patchsets are posted. StoryBoard doesn't duplicate discussion at patchset-level: comments in StoryBoard are more about the overarching story and progress towards implementing / solving it.

Gerrit updates tasks status in StoryBoard, when those are linked to a specific review. When a change is merged or abandoned, the corresponding task status is automatically updated. This gives us an accurate view on which tasks are still to be done vs. which ones are already completed.

Relationship with git

Git is where the code lands. Commit messages give a precise history of the changes that were merged in various branches. However, commit-level changelogs are noisy, and fail to provide a clear, categorized list of what was shipped in a given release.

StoryBoard leverages tasks, stories and story types, and tracks in which release tag completed tasks are first shipped to build clear, categorized release pages that convey more useful information than raw changelogs.