Page History

Page Status: 

Overview

The goal of the VNF Guidelines and Requirements project is to provide guidance to VNF providers on the guidelines, rules, and specifications to which a VNF must adhere to correctly onboard and operate within ONAP.  These rules span across the VNF's lifecycle and are influenced by the various components that comprise ONAP as well as various industry standards that are required for interoperability.

...

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

Setting Up the Project

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

Editing the Documents

1. 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 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-#####

2. 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

3. 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   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.
4. Once you are satisfied with your change, then it will be time to commit and submit your changes for review

Commiting and Submitting Your Changes

1. Initialize your repository to work with Gerrit

   Code Block
   > git review -s

2. Add your changes to git

   Code Block
   > git add --all

3. Commit your changes

   Code Block
   > git commit -s

4. Your default, configured editor will open to provide a commit message.  Please ensure that your commit message adheres to the ONAP Commit Messages standards or your submission will be automatically rejected by Gerrit. 
   1. NOTE: At the bottom of your commit message be sure to include the line Issue-ID: VNFRQTS-####  that corresponds to the JIRA ticket you opened for this change.
5. Now you are ready to push your changes to Gerrit using git review
   

   
   

   Code Block
   > git review

6. Once you have successfully pushed the change up, please log into Gerrit and add reviewers

   1. Log into your dashboard
   2. See your Outgoing Reviews and click on the link corresponding to your review
   3. Click Add to add reviewers
   4. Image Added
   5. Add the following reviewers to your review
      1. Steven Wright
      2. Hagop Bozawglanian
      3. Any additional reviewers you feel would add value
7. Please pay attention to your inbox following the creation of your review.  The ONAP Jobbuilder will attempt to build your documentation and may reject the change if there are problems.  Please see it's messages and resolve any issues that it raises.
   
   

Making Updates

1. Often there will be changes you will need to make to get this working correctly.
2. Make any changes locally based on the feedback and add those those changes to be committed.

> git add --all

3. Rather than a normal commit, we'll just amend your previous commit.

> git commit --amend

4. Finally resubmit your change via git review and your change will be updated

> get review

After Your Changes Are Accepted and Merged

1. Update your JIRA ticket to completed
2. Thank you for your contribution!