Contributing Directed Graphs

Table of Contents

1 Introduction
2 DG gerrit directory layout
3 DG naming convention
4 DG versioning
5 Adding A New DG To Gerrit

Introduction

As project work is assigned to a developer he or she may need to create or update directed graphs. This page explains the layout of the repositories that contain directed graphs as well as best practices.

DG gerrit directory layout

Below I use service-logic as an example, platform-logic uses similar conventions, but slightly different names.

The service-logic project is an example of a gerrit repository containing directed graphs.

service-logic/<module> - top level directory and maven project representing a module

service-logic/src/main.xml - will contain the XML files for the DGs related to that module. This is the target code that will be installed into a given environment (IT for example). Only files in this directory are loaded.

service-logic/src/main/json - will contain the JSON files for the DGs related to that module. This is the source code it can be loaded into dgbuilder to be modified or converted to the target format (XML) to be ran. The source itself is never executed directly.

service-logic/src/main/resources/graph.versions - lists out which DGs should be activated. After a DG has been activated it will be running in that environment. Behind the scenes this is just updating a column in the database.

DG naming convention

See FileNaming (fill in link to Best Practices)

DG versioning

See Versioning (fill in link to Best Practices)

Adding A New DG To Gerrit

If you are working on platform-logic, service-logic or a similar project you need to follow these steps.

The below links are all to service-logic if you are working on a different project the file layout should be the same.

Follow the below steps to successfully add a new DG.

Always run validate XML in DG Builder (this causes basic XML validation to happen which catches errors)
Always run upload XML in DG Builder (this causes schema validation to happen which catches errors)
If the DG is being added to a NEW directory - read the README (fill in link).
Always save JSON file after making changes (You cannot recover source files from the XML, so you need to keep them in synch)
Always generate a new XML file with a name matching the JSON file (The standard is for the names to match so please follow this).
commit the src and xml files under the appropriate directories for that module (refer to git directory layout above if this isn't clear).
update the graph.versions file for the appropriate module.