needextend

New in version 0.7.0.

needextend allows to modify existing needs. It doesn’t provide any output, as the modifications get presented at the original location of the modified need.

.. needextend:: <filter_string>
   :option: new value
   :+option: additional value
   :-option:

The following modifications are supported:

  • option: replaces the value of an option

  • +option: add new value to an existing value of an option.

  • -option: delete a complete option.

The argument of needextend must be a Filter string, which defines the needs to modify.

needextend can modify all string-based and list-based options. So also links can be added or tags can get deleted.

Example

.. req:: needextend Example 1
   :id: extend_test_001
   :status: open
   :author: Foo
   :tags: tag_1, tag_2

   This requirement got modified.

   | Status was **open**, now it is **[[copy('status')]]**.
   | Also author got changed from **Foo** to **[[copy('author')]]**.
   | And a tag was added.
   | Finally all links got removed.

.. needextend:: id == "extend_test_001"
   :status: closed
   :+author: and me
   :+tags: new_tag
Requirement: needextend Example 1 extend_test_001 ../_images/arrow-right-circle.svg
status: closed
tags: tag_1, tag_2, new_tag
author: Foo and me
duration: None
completion: None
links outgoing: FEATURE_1, FEATURE_2, FEATURE_3

This requirement got modified.

Status was open, now it is closed.
Also author got changed from Foo to Foo and me.
And a tag was added.
Finally all links got removed.

Single need modification

If only one single need shall get modified, the argument of needextend can just be the need-id.

.. req:: needextend Example 2
   :id: extend_test_002
   :status: open

.. needextend:: extend_test_002
   :status: New status
Requirement: needextend Example 2 extend_test_002 ../_images/arrow-right-circle.svg
status: New status
duration: None
completion: None

Attention: The given argument must fully match the regular expression defined in needs_id_regex and a need with this ID must exist! Otherwise the argument is taken as normal filter string.

Monitoring modifications

All needs have this two internal parameters:

  • is_modified: A boolean value. Default False

  • modifications: A number. Default 0.

If a need gets changed by a needextend directive, is_modified is changed to True. Also the modifications number is increased by one. +1 for each executed needextend on this need.

To see these values, use :layout: debug on the need or by Defining own layouts.

Also filtering for these values is supported:

We have :need_count:`is_modified` modified needs.

.. needtable::
   :filter: "needextend" in title
   :columns: id, title, is_modified, modifications

We have 5 modified needs.

ID

Title

Is Modified

Modifications

extend_test_001

needextend Example 1

True

1

extend_test_002

needextend Example 2

True

1

extend_test_003

needextend Example 3

True

1

extend_test_004

needextend Example 4

False

0

extend_test_005

needextend Example 5

True

1

extend_test_006

needextend Example 6

True

2