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 (affecting the same project and branch). 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.

Finally, StoryBoard can also be used to submit bug reports, even if you don't sign up for fixing them or know the exact tasks which will be required to solve it. A bug report is just another story we need to track the completion of.

Relationship with code review system

The code review system is 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.

The code review system 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 version control system

The VCS 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.

Notes

This exercise is interesting. Most of the vision is pretty coherent, including the whole "organize your work using task lists" part. But it also reveals two areas that are slightly less coherent and may need more investigation.

One is the bug tracker vs. task tracker tension. StoryBoard is primarily a task tracker, but we want it to support bug reporting workflows as well. Filing a story with a single task we hope matches the affected code base, a bit in a vacuum, might not be the best way to ensure that those reports are triaged properly. I still think it's the easiest way, but alternatives include using specific StoryBoard "projects" that would let us track bug triaging tasks, or using a issue reporting/triaging tool that would result in tasks being filed if issues are found to be valid.

The second is the git changelog vs. StoryBoard release page tension. StoryBoard is primarily a task-TODO tracker, not really a task-completed tracker. We want lists of completed stories, but at project/milestone level (while stories are project-agnostic). We also want the list to be reasonably complete (while only the git logs are complete). It's possible that those elaborate changelogs would look better if we built them from commit messages or git notes with specific keywords to identify implemented features, fixed bugs and CVE patches.