Added specification for storyboard story tags
This specification explains how story tags should be handled in StoryBoard. Change-Id: I66dcaa700e4a64d25b2c0a7e05fec9ff2e12f5d6 Story: 98
This commit is contained in:
Thierry Carrez
parent
d5b3824759
commit
7434bdbc77
199
specs/storyboard_story_tags.rst
Normal file
199
specs/storyboard_story_tags.rst
Normal file
@ -0,0 +1,199 @@
|
|||||||
|
::
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
==========
|
||||||
|
Story Tags
|
||||||
|
==========
|
||||||
|
|
||||||
|
https://storyboard.openstack.org/#!/story/98
|
||||||
|
|
||||||
|
StoryBoard needs to support tagging to allow for free-form classification
|
||||||
|
of stories by its users. It will also allow to port current tag-driven
|
||||||
|
workflows from Launchpad to StoryBoard, facilitating the transition.
|
||||||
|
|
||||||
|
Problem description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Definition
|
||||||
|
----------
|
||||||
|
In information systems, a tag is a non-hierarchical keyword or term assigned
|
||||||
|
to a piece of information. This kind of metadata helps describe an item and
|
||||||
|
allows it to be found again by browsing or searching.
|
||||||
|
|
||||||
|
It also lets teams implement basic team-specific workflows, where the presence
|
||||||
|
or absence of a tag is used to derive state (rather than endlessly overloading
|
||||||
|
the data model with team-specific fields).
|
||||||
|
|
||||||
|
Historical usage
|
||||||
|
----------------
|
||||||
|
In OpenStack, Launchpad bug tags are currently used to:
|
||||||
|
- classify the affected submodule or domain of expertise ("xen")
|
||||||
|
- identify bugs that could be fixed by new contributors ("low-hanging-fruit")
|
||||||
|
- trigger notifications for subset of bugs ("security")
|
||||||
|
- define sets of bugs used as part of the release process ("juno-rc-potential")
|
||||||
|
|
||||||
|
Convergence in the use of standard tags is encouraged in Launchpad by the
|
||||||
|
ability to define "official tags" that the UI suggests in type-ahead.
|
||||||
|
|
||||||
|
See the current "official tags" used by OpenStack at:
|
||||||
|
https://wiki.openstack.org/wiki/BugTags
|
||||||
|
|
||||||
|
Launchpad tags can be specified in search forms and subscription rules.
|
||||||
|
This lets users easily designate and retrieve subset of bugs in a reusable way.
|
||||||
|
|
||||||
|
Note that Launchpad blueprints notoriously do NOT support tags: this is seen
|
||||||
|
as a major feature gap (along with lack of comment, search...) supporting
|
||||||
|
the move to a new tool.
|
||||||
|
|
||||||
|
Proposed change
|
||||||
|
===============
|
||||||
|
|
||||||
|
We propose to let users associate tags to StoryBoard stories. Tags should be
|
||||||
|
supported as a search parameter (to retrieve stories associated with a given
|
||||||
|
tag). Users should be able to subscribe to tags (and get notified when tagged
|
||||||
|
stories are modified).
|
||||||
|
|
||||||
|
Tags should only contain lowercase alphanumeric characters, plus dash (-) and
|
||||||
|
underscore (_) characters. To encourage convergence, uppercase characters
|
||||||
|
should be automatically converted to lowercase on input. Their length is
|
||||||
|
limited to 30 characters.
|
||||||
|
|
||||||
|
In order to enable various use cases for tags, we propose three types of tags:
|
||||||
|
|
||||||
|
Free-form tags
|
||||||
|
--------------
|
||||||
|
Free-form tags are keywords that can be freely set (and unset) by any
|
||||||
|
authenticated user of StoryBoard. They may use any name they want, as long
|
||||||
|
as it respects the abovementioned syntax rules.
|
||||||
|
|
||||||
|
System tags
|
||||||
|
-----------
|
||||||
|
System tags are predefined keywords that we want to recommend usage of.
|
||||||
|
|
||||||
|
It is a feature needed to increase convergence in tag usage, and reduce
|
||||||
|
tag consolidation manual tasks. As an example, take a system tag called
|
||||||
|
"documentation", that would be used to signal a potential documentation impact.
|
||||||
|
The tag input field could use type-ahead to strongly suggest the correct
|
||||||
|
keyword when you start typing "doc..", hopefully reducing variants like "doc",
|
||||||
|
"docs", "documentations", etc.
|
||||||
|
|
||||||
|
System tags should come with a description of their intended usage, which
|
||||||
|
should be accessible as part of the StoryBoard interface.
|
||||||
|
|
||||||
|
System tags can be freely set (and unset) by any authenticated user of
|
||||||
|
StoryBoard. They shall be defined by superusers using a specific admin UI.
|
||||||
|
|
||||||
|
Protected tags
|
||||||
|
--------------
|
||||||
|
Protected tags are keywords that would be reserved for use by a specific group.
|
||||||
|
Members of the protected tag owner group should be the only ones to be able to
|
||||||
|
set or unset the tag. For example, the release managers team could use a
|
||||||
|
protected "juno-ffe" tag to track that a Juno feature freeze exception was
|
||||||
|
granted to the corresponding story, and easily build lists of open feature
|
||||||
|
freeze exceptions.
|
||||||
|
|
||||||
|
Since tags are applied at story-level, any project-specific protected tag
|
||||||
|
should be project-specific itself. For example if Nova drivers want to track
|
||||||
|
that the spec for a given story has been approved, they could use a
|
||||||
|
"nova-approved" protected tag to that effect. Since the owner groups are
|
||||||
|
distinct, an equivalent tag for Cinder drivers would have to be distinct (and
|
||||||
|
for example be called "cinder-approved").
|
||||||
|
|
||||||
|
Protected tags should come with a description of their intended usage and owner
|
||||||
|
group, and you should be able to access that information as part of the
|
||||||
|
StoryBoard interface. Protected tags shall be defined by superusers using a
|
||||||
|
specific admin UI.
|
||||||
|
|
||||||
|
NB: Protected tags are a new feature: they are not needed for Launchpad feature
|
||||||
|
parity. However, they are a convenient way to implement a number of workflows
|
||||||
|
in StoryBoard that would otherwise need to be hardcoded. Given the very
|
||||||
|
dynamic nature of OpenStack development, it's easier to give users concepts
|
||||||
|
that they can build experimental workflows with than to require code changes
|
||||||
|
or configuration changes to let them implement them.
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
The "tag" concept could be extended to other citizens of StoryBoard, like tasks
|
||||||
|
or projects.
|
||||||
|
|
||||||
|
I think allowing tags to be applied to tasks would confuse the UI a lot and
|
||||||
|
result in non-intuitive behavior (do new tasks inherit other tasks
|
||||||
|
tags ?). The experience from Launchpad usage (where the tag is applied to the
|
||||||
|
bug rather than on the task) shows that tags apply to most tasks anyway, and
|
||||||
|
humans can read that information in a smart way. The value of this additional
|
||||||
|
granularity in information is limited, while the cost in extra data entry and
|
||||||
|
UI overcrowding is high.
|
||||||
|
|
||||||
|
Project tags could make sense to designate informal groups of projects.
|
||||||
|
However we already implement projectgroups, which should ideally be cheap to
|
||||||
|
create and therefore cover that use case.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Implementation details should be left to the person that would do the
|
||||||
|
implementation work. What follows is just a suggestion.
|
||||||
|
|
||||||
|
Each type of tag should be quickly identifiable. The proposed implementation
|
||||||
|
would represent them with different background colors:
|
||||||
|
|
||||||
|
* Free-form tags would be represented with a neutral background (grey color)
|
||||||
|
* System tags would be represented with a cold color (blue/green color)
|
||||||
|
* Protected tags would be represented with a hot color (red/yellow color)
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
Primary Assignee:
|
||||||
|
TBD
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
* Create an API to define system tags and protected tags
|
||||||
|
* Create an API to associate tags to stories
|
||||||
|
* Add tag data in story details API responses
|
||||||
|
* Teach the storyboard-webclient to use those new APIs
|
||||||
|
|
||||||
|
Repositories
|
||||||
|
------------
|
||||||
|
No new repositories.
|
||||||
|
|
||||||
|
Servers
|
||||||
|
-------
|
||||||
|
No new servers.
|
||||||
|
|
||||||
|
DNS Entries
|
||||||
|
-----------
|
||||||
|
No new DNS entries.
|
||||||
|
|
||||||
|
Documentation
|
||||||
|
-------------
|
||||||
|
TBD
|
||||||
|
|
||||||
|
Security
|
||||||
|
--------
|
||||||
|
Free-form and system tags may be set and unset by any authenticated user.
|
||||||
|
They may therefore be used for spamming (set), or info destruction (unset).
|
||||||
|
However this is not different from any other potentially more lucrative fields
|
||||||
|
(like title or description). The benefit of letting anyone authenticated
|
||||||
|
edit data in a task/bug tracker generally outweighs those drawbacks, which are
|
||||||
|
not specific to tags.
|
||||||
|
|
||||||
|
Testing
|
||||||
|
-------
|
||||||
|
TBD
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
Protected tags will need "StoryBoard Teams API and management spec" to be
|
||||||
|
approved and implemented first (specs/storyboard_teams.rst).
|
||||||
Loading…
x
Reference in New Issue
Block a user