Directed Graph: Best Practices
- FREEMAN, BRIAN D
Table of Contents
Graph Size
For organization and re-use graphs should strive to be small. In general a graph should be under 100 nodes. This is not a hard rule, but a strong suggestion.
Because Directed Graphs can be patched outside of a release without a reboot there is a strong desire to encapsulate everything in a single directed graph.
This thinking has led to graphs as large as 671 nodes. A directed graph can be thought of as a function. Creating large functions in any language has drawbacks so the same considerations should be applied to directed graph.
Below are two strategies for reducing the size of directed graphs.
Reducing Graph Size
Use of Call Nodes
Once a graph reaches over 50 nodes the author should examine if large chunks of nodes should be broken into a separate graph, this is similar to creating a new function. The original graph should use a call node to call this new graph. Authors tend to make the net graph's RPC name a variant of the original. For example vnf-topology-operation has sub-graphs for vnf-topology-assing, vnf-topology-delete, etc. The RPCs in the sub-graphs do not have to be in the original yang model (VNF-API.yang in this example.
Use of Execute Nodes
Similar, a group of nodes doing complex, re-usable logic should be replaced with an “execute” node. Execute nodes are java classes and are much easier for complex operations.
IPAddressTools is an example where early on we looked at all the ip address bit manipulations and cidr calculations and determined that an execute node would be more appropriate. It now has 10’s of methods to deal with all the different ipv4 and ipv6 manipulations we need. Another advantage of complex logic in an execute node is that an execute node can include unit tests as part of the build process.
If possible, you should design your execute node to be idependent of the yang model application it is running in. Take a list of parameters or a context memory branch as input and write data to the parameter so that other applications can re-use the execute node.
Versioning of Directed Graph files
there is no reason to create Multiple files to keep track of previous version.
Every commit should increase the minor version of a graph.
The XML and JSON should always be on the same version and be committed together. Never should only one file be changing.
Developers should put the version in the commit message, so the relationship between git revision and graph version is clear.
Legacy graphs that use attributes which are no longer supported and graphs which no longer run should be placed into archive or deleted.
Versioning Scheme
release.majorChange.minorChange EX 1702.00.01
If the release has changed update the release and reset the major/minor IE 1702.00.01 -> 1704.00.00
If a major change (user story) is implemented bump the major version and reset the minor 1702.00.01 -> 1702.01.00
If a minor change (bugfix or otherwise) bump the minor 1702.00.01 -> 1702.00.02
Never make a change without changing the version of the graph. If this happens it is unclear when the changes were delivered to a test environment.
File Naming
Do not include the version number in the file name. This leads to one file per version which creates confusion and wastes space.
In the rare case multiple versions of a graph are required. Old versions may contain the version number when multiple version support is required, the latest version should not have a version in the file name.
The file name should follow the format moduleName_method_rpcName.fileExt IE L3BAREUCPE-API_method_save-create-vnf.json.
JSON and XML names should be identical except for the extension IE L3BAREUCPE-API_method_save-create-vnf.json and L3BAREUCPE-API_method_save-create-vnf.xml.