Versions Compared

Old Version 6

changes.mady.by.user Hagop Bozawglanian

Saved on

compared with

New Version 7

changes.mady.by.user Trevor Lovett

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.



Info
07-09-2018: This proposal has been modified to reflect further refinement in the approach to make the process simpler for authors.

For any contributors who would like to edit the VNF Requirements document.



The enhanced toolkit that we are proposing has been developed to help users edit the VNF Requirements documents in a quicker fashion, as well as adding more functional capabilities of the this project. Outlined in this document are the added tools we are proposing:

Current Process

Flow

  1. All Requirements manually maintained within RST files.

    1. For example:
      **Resource Description**
-------------------------
* R-77707 The VNF provider **MUST** include a Manifest File that contains a list of all the components in the VNF package.
* R-66070 The VNF Package **MUST** include VNF Identification Data to uniquely identify the resource for a given VNF provider. The identification data must include: an identifier for the VNF, the name of the VNF as was given by the VNF provider, VNF description, VNF provider, and version.
* R-69565 The VNF Package **MUST** include documentation describing VNF Management APIs. The document must include information and tools for:

  2. No additional information about individual requirements is maintained.

    1. For example:
      1. Release
      2. Testable
      3. etc.

  3. Requirements must be manually updated in multiple locations within the RST files.

    1. Requirements must be managed within the proper Chapter and Section, AS WELL AS within the Appendix.

Proposed Process

Flow

All Requirements are maintained as JSON Formatted in one document.

For example:"R-01334": { "description": "

Objectives

This proposal aims to address the following objectives:

  • Associate standard, structured metadata with each requirement to aid in a variety of use cases such as dependency tracking, searching, filtering, and reporting.
  • Export requirements in a machine-readable format for use by other projects such as the VNF Validation Project.
  • Generate different formats and outputs without duplicating requirement content (ex: appendices, tables, CSV files, etc.)
  • Provide traceability within the document between requirements, test cases, and other items within the documents.

Approach

Requirements will still be maintained in the reStructuredText file, but they will be shifted to structured directives using the sphinxcontrib-needs extension.  This extension provides a way to meet each of the needs above.

Here is an example of a requirement after the conversion:

Code Block
languagetext
titleRequirement Example
.. req::
	:id: R-01334
	:keyword: MUST
	:target: VNF
	:links_incoming: R-01335


	The VNF **MUST** conform to the NETCONF RFC 5717, Partial Lock Remote Procedure Call
.", "id": "R-01334", "section": "Configuration Management", "requirement target": "VNF", "RFC2119 keyword": "MUST" }

Metadata Retained for each Requirement

Current fields within metadata with possible fields:
  • description
    1. Any string describing the requirement.
  • id
    1. Number of the requirement formatted as an 'R-' followed by 5 numbers, must be unique : "R-XXXXX"
  • section
    1. Proposed section values:
      1. Configuration Management
      2. Management
      3. Monitoring & Management
      4. VNF Design
      5. VNF Devops
      6. VNF Modularity
      7. VNF On-boarding and package management
      8. VNF Resiliency
      9. VNF Security
    2. Option to add a new section as well.
  • requirement target/component/subject (final field name not decided)
    1. Proposed field values:
      1. VNF
      2. PNF
      3. xNF
      4. VNF-c
      5. VNF Package
      6. VNF Heat Template
    • RFC2119 keyword
    Proposed field values:
  • MUST
  • SHOULD
    • MUST NOT

    RST ↔JSON Linking to simplify number of locations that need to be managed

    For example:
    **Resource Description** ------------------------------------------- R-77707 R-66070 R-69565

    These requirement definitions can be processed by the sphinxcontrib-needs extension and used in a variety of ways.
    • Summary tables can be created via a needtable directive which provides a number of capabilities such as:
      • Export to a variety of formats such as CSV, Excel, and PDF
      • Filtering
      • Sorting
    • All requirements can be exported as JSON file for consumption by other projects.
    • By default metadata is hidden in the HTML document, but can easily be expanded to allow readers to learn more about the requirement.
    Metadata Standards
    The following table outlines the proposed standard metadata elements that will be associated with the requirements. This list may change over time.
    Field Name
    Required
    vs. Optional
    		Data TypeValid Values/FormatNotes
    targetRequiredString
    VNF, VNFC, VNF PROVIDER, VNF HEAT ORCHESTRATION TEMPLATE,
    VNF PACKAGE, XNF
    		The component to which the requirement applies.
    keywordRequiredStringMUST, MUST NOT, SHOULD, SHOULD NOT, MAYThe RFC 2119 keyword for the requirement
    introducedOptionalStringlower case release name (ex: bejing, casablanca)The release the requirement was initially introduced
    updatedOptionalStringlower case release nameThe release the requirement was last modified
    impactsOptionalList of StringComma separated list of ONAP components (ex: so, sdc)The various ONAP components that need to be aware of any changes to the requirement
    validation_modeOptionalStringstatic, stand_alone, in_service
    How the requirement is validated:
    static - validated by statically inspecting the VNF package data
    stand_alone - validated by running tests against the VNF itself
    in_service - validated in the context of a full or partial ONAP deployment
    validated_byOptionalList of String
    Comma separated list:
    vvp, vnfsdk, sdc
    		Projects that implement validations of this requirement.
    test



    test_case



    test_file



    notes