Page Comparison

...

The method for contributing or interacting with the VNF Requirements project depends on the type of contribution.  Please refer to the following table for guidance on the best method to use.

Submitting Gerrit Reviews

TODOThe easiest way for the VNF Requirements project to accept and incorporate changes is through merge/review requests via Gerrit.  This will enable the team and community to review your proposed changes in context,collaborate on changes, and ensure contributions adhere to the standards of the tool chain required to build the documentation.   

Contributing in this manner will require the setup of some tools on your local machine or environment.

Prerequisites

• Linux Foundation ID: You will need this to access JIRA and Gerrit.  You can register for an ID here.

• Knowledge of reStructuredText (RST): All documentation at ONAP is authored in RST.  For the most part you can follow the style of other requirements and content without being an RST expert, but understanding basics may be useful.  The ONAP Documentation project has some useful guides and tutorials here.

• Python 2.7, 3.6+: You will not need to write any Python code, but it is required to generate the documentation from reStructuredText.  If needed, you can find installation instructions for your system here.
• Git: This is the version control tool used by ONAP. If not present on your system, then refer to Git's Getting Started - Installation Guide for more information
• Git Review: This is the command line extension to Git to enable changes to be submitted to review to Geritt.  This needs to be installed after you have installed Git and Python.

• Tox: This is a tool to run the build.  It must be installed after you install Python.  Install it using pip.

  Code Block
  > pip install tox

• VNF Requirements Standards: Familiarize yourself with the VNFRQTS Requirement and Documentation Standards

Setup

Before submitting your first change, you will need to configure Git and Gerrit to work together.  That is outside the scope of this guide, but you can find more information here.

Process

1. Before submitting a change, open a JIRA ticket to introduce the change.
   1. Project: VNF Requirements
   2. Issue Type: Story for changes that can be incorporated via a single change, Epic if the updates will require multiple commits.  If you need an Epic, then you will need a story for each set of changes you wish to make.  If the changes you are proposing are substantial, then you may need to create an entry in Proposals for discussion before proceeding with your requirement changes.
   3. Summary: Descriptive summary of the changes to be made
   4. Fix Version: Target ONAP release for your changes
2. Clone the appropriate repository for your content (see VNFRQTS Requirement and Documentation Standards for guidance and links).  
3. Navigate to the directory you cloned the repository into

4. Run the following command to generate the documentation and verify everything works properly
   
   

   Code Block
   language bash title build docs
   <project-dir> tox -e docs

5. If everything works properly, this will generate the HTML documentation in the docs\_build\html directory
6. If you will be adding requirements (NOTE: this is only applicable when working on the vnfrqts/requirements repository), then you will need a block of requirement IDs to use.  Determine the number of requirements you intend to add and use the make_ids.py to generate the requirement IDs (don't worry you can always generate more)

   

   The following command will generate 5 random, unique requirement IDs for your use.  The requirement IDs you generate will not conflict with any requirement already in the document, but they are not strictly reserved.  The build process will throw an error if your requirement ID is a duplicate.

   
   

   Code Block
   language bash title Generate Requirement IDs
   <project-dir> python make_ids.py 5 R-##### R-##### R-##### R-##### R-#####

7. Edit the RST documents in the docs folder.  Be sure to format any requirements according using the .. req:: directive as defined in the standards. 
   
   

   Code Block
   language text title Example Requirement
   .. req:: :id: R-12345 :keyword: MUST :target: VNF PACKAGE :introduced: casablanca :impacts: sdc :validation_mode: static The VNF Package **MUST** include element XYZ as part of the CSAR package in the ABC directory

8. After you have made your changes, rebuild the documentation using the tox -e docs command, and view the changes in browser to ensure they are formatted correctly.  This will also regenerate the JSON version of the requirements that are located in docs/data/needs.json.  This is the file make_ids.py uses to ensure new requirement IDs do not conflict and the JSON version is also downloadable via the Requirements List chapter of the Requirements document.