.. _/spec/stories:

Stories
=======
*As a developer I want to define application features and track which have been already implemented, verified and documented.*


Stories, which implement the L3 metadata, can be used to track
implementation, test and documentation coverage for individual
features or requirements. Thanks to this you can track
everything in one place, including the project implementation
progress.

In addition to the attributes defined here, stories also
support common :ref:`/spec/core` attributes which are shared
across all metadata levels.


**Examples:**


.. code-block:: yaml

   story:
       As a user I want to see more detailed information for
       particular command.
   description:
       Different verbose levels can be enabled by using the
       option several times.
   example:
     - tmt test show -v
     - tmt test show -vvv
     - tmt test show --verbose
   link:
     - implemented-by: /tmt/cli.py
     - documented-by: /tmt/cli.py
     - verified-by: /tests/core/dry
   priority: must have

.. _/spec/stories/example:

example
^^^^^^^

Instructive examples of real-life usage.



One example is worth thousand words. Providing a few,
well selected, examples helps to understand quickly
and get inspiration for initial experimenting.

One or more examples can be defined, each of them is rendered
into a separate box during export. Must be a ``string`` or a
``list of strings``.


**Examples:**


.. code-block:: yaml

   # Short one-line example
   example: tmt run discover



.. code-block:: yaml

   # Preserve line breaks using the '|' modifier
   example: |
       tmt run --until execute
       tmt run --last report



.. code-block:: yaml

   # Use a list to define multiple examples
   example:
     - tmt run --until execute
     - tmt run --last report



.. code-block:: yaml

   # Several multiline examples
   example:
       - |
           # Check validity of the plans
           tmt plan lint
       - |
           # Check which tests would be run
           tmt run discover


**Status:** implemented

* Implemented by `/tmt/base.py <https://github.com/teemtee/tmt/tree/main/tmt/base.py>`_

.. _/spec/stories/priority:

priority
^^^^^^^^

User story priority

*As a stakeholder I want to define priority for each user story so that it's clear which user stories are essential and must be implemented, which are important and which are desirable but not necessary.*


All user stories are important, but they are prioritized to
deliver the greatest and most immediate benefits early. When
working on implementation developers should prioritize their
tasks to cover the most important features first.

The following four values based on the `MoSCoW method`__ are
supported:

must have
    critical for the project success, must be delivered on
    time in order to consider the implementation as successful

should have
    important stories which need to be covered but are not as
    time-critical and can be delivered later if there are not
    enough resources

could have
    desirable but not necessary and could improve the user
    experience or customer satisfaction for a little
    development cost

will not have
    least-critical, lowest-payback items, not planned into the
    current schedule, might be dropped or reconsidered for
    inclusion in a later timebox

Must be a ``string`` with one of the above-mentioned values.

__ https://en.wikipedia.org/wiki/MoSCoW_method


**Examples:**


.. code-block:: yaml

   # This is an essential feature
   priority: must have


**Status:** implemented and verified

* Implemented by `/tmt/base.py <https://github.com/teemtee/tmt/tree/main/tmt/base.py>`_ 


* Verified by `/tests/story/priority <https://github.com/teemtee/tmt/tree/HEAD/tests/story/priority/main.fmf>`_

.. _/spec/stories/story:

story
^^^^^

User story describing the feature to be implemented



This is a **required** attribute. Each story has to define or inherit a ``story`` definition.

**Examples:**


.. code-block:: yaml

   story:
       As a user I want the application to do this and that
       so that I can achieve this and that.


**Status:** implemented

* Implemented by `/tmt/base.py <https://github.com/teemtee/tmt/tree/main/tmt/base.py>`_

.. _/spec/stories/title:

title
^^^^^

Title to be used when generating documentation

*As a story writer I want to specify a title which should be used when generating online documentation from user stories.*


When converting user stories into the reStructuredText format in order to render content into online documentation it is sometimes useful to provide a custom user story title rather then using the story name which can be too short to describe well the section content. Must be a ``string``.

**Examples:**


.. code-block:: yaml

   title: Nice title


**Status:** implemented

* Implemented by `/tmt/base.py <https://github.com/teemtee/tmt/tree/main/tmt/base.py>`_