StoryBoard task branch support

Spec describing how branch-specific tasks could be implemented in
StoryBoard.

Change-Id: Ib02baca0044894712fd5057718b83ca853c53b5d
This commit is contained in:
Thierry Carrez 2014-12-05 13:38:09 +01:00
parent 4e3ab2f8b2
commit e2cb246877

View File

@ -0,0 +1,179 @@
::
This work is licensed under a Creative Commons Attribution 3.0
Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode
..
This template should be in ReSTructured text. Please do not delete
any of the sections in this template. If you have nothing to say
for a whole section, just write: "None". For help with syntax, see
http://sphinx-doc.org/rest.html To test out your formatting, see
http://www.tele3.cz/jbar/rest/rest.html
===============================
StoryBoard support for branches
===============================
StoryBoard needs to support branch-specific tasks in order to be usable for
OpenStack bug tracking.
Problem description
===================
Rationale
---------
StoryBoard is a task tracker, and its main use case is the ability
to track resolution of a specific issue (story) across multiple teams.
Most OpenStack projects maintain stable/* branches. A few of them use feature
branches. As we near release, projects make use of temporary proposed/*
branches. All bugs need to be fixed in the master branch, but some of them
will also need to be fixed in other branches, and that involves the work of a
lot of separate subteams. So we need the ability to track tasks across
branches (bugfix or vulnerability fix backports) as much as we need to
track tasks across projects.
Historical usage
----------------
Launchpad supports series-specific tasks, which can be used to emulate branch
support. A series in Launchpad is like a release cycle ("juno", "kilo") which
contains multiple release "milestones". By default in Launchpad a task applies
to the series under development, but you can create series-specific tasks
to target past series. An example of that can be seen at:
https://bugs.launchpad.net/keystone/+bug/1354208
That said, Launchpad implementation becomes very confusing because you can
also explicitly create a task targeting the current series, in which case
the main task is disabled with a confusing "status tracked in..." message.
Proposed change
===============
Project names and git repository links
--------------------------------------
Currently the project names are used for two different things. They represent
the project name in StoryBoard views and dropdowns, and they specify the name
of the git repository that is associated with that project.
This dual meaning results in confusion when StoryBoard is used to support
projects that are not backed by a code repository, in a general waste of
UI space (due to the mention of the GitHub organization in the project name),
and in the inability to have projects in different git servers (all projects
are assumed to come from git.openstack.org).
Since for branch support we'll need to be able to query git repositories for
their branches, this sounds like the right moment to specify the git
repository location separately from the project name.
Task branches
-------------
Projects in StoryBoard may define multiple task branches. Each project has
at least one task branch (called "master"). If a project has only one task
branch, the UI should optimize and ignore that concept altogether, to
simplify the views.
If a project is linked to a git repository, task branches may be created
automatically from branches defined in that git repository (using for example
a daily cron job). Each project may opt to have task branches autocreated
from its code repository branches. This should not prevent them from manually
creating an additional task branch.
Task branches should be able to expire: they would still show in past tasks,
but you would not be able to select them for new tasks. Deleted branches
would automatically result in expired task branches.
Note that the task branch concept degrades gracefully for non-code projects,
which can opt to manually define several areas of work as task branches, or
ignore the concept altogether and use the default branch.
Implementation
==============
Implementation details should be left to the person that would do the
implementation work. What follows is just a suggestion.
The Project table would have two new columns:
* 'code_repo', which would hold a URL describing the code repository,
like git://git.openstack.org/openstack/nova
* 'autocreate_branches', which would tell StoryBoard to try to create task
branches automatically from the branches declared on that code repository
A new Branch table would be created, with the following columns:
* 'project_id', mapping to the owner project
* 'branch_name', with the name of the task branch
* 'creation_date', date of creation
* 'expired', a binary flag that marks branches that should no longer be
selectable in tasks
* 'expiration_date', last date the expired flag was switched to True
* 'autocreated', a flag that marks autocreated entries, so that they can
be auto-expired when the corresponding branch is deleted in the git repo
By default, all projects would start with a single "master" branch.
The Task table would have one new column:
* 'task_branch', which would point to the affected branch in the project.
Defaults to the 'master' branch for that project.
The UI would show the 'branch' only if multiple different branches are
defined in the project, saving valuable horizontal space for projects that
don't have a use for this concept.
Assignee(s)
-----------
Primary Assignee:
TBD
Work Items
----------
TBD
Repositories
------------
No new repositories.
Servers
-------
No new servers.
DNS Entries
-----------
No new DNS entries.
Documentation
-------------
TBD
Security
--------
Manual branch creation should be restricted to an admin set of users, to
avoid accidental or spurious creation of project branches.
Testing
-------
TBD
Dependencies
============
This proposal is not dependent on any other, but it is a prerequisite for
task milestone or story type support.