Provide specification for how naming and versioning business logic conventions should be used.

[joewheaton]

@MattReimer, it has come up several times now where we have a need to keep an existing or old version of business logic, but a new version of a tool or model emerges and we need something better than old and new or final suffixes or prefixes. We have punted on this previously in some false sense of delusion that it would not be that common. We have good guidelines for versioning of tools. Can you please give us some simple guidelines for how you would like this done?

Also, where does the documentation belong for this? We originally had some stuff (targeted at developers and curators) here: https://tools.riverscapes.xyz/gnat/

Later, @philipbaileynar made up some new and updated (and of course conflicting stuff) here: https://rave.riverscapes.xyz/Technical_Reference/business-logic.html

This is motivated by #476

[joewheaton]

I was trying to remind myself how RAVE looks for business logic. My memory was failing.

I think that for the current live warehouse @MattReimer is already "registering" if you will one VBET Business Logic to be the default display for each version of them model based on the old "Program" (e.g. https://github.com/Riverscapes/RiverscapesXML/blob/master/Programs/Anabranch/Program.xml)?

RiverscapesXML/Programs/Anabranch/Program.xml

Line 34 in 9744ec2

<Product id="VBET" name="Valley Bottom Extraction Tool (VBET)" folder="VBET" url="" />

So , is the current plumbing for business logic looking at the Program <id= tag? and seeing if the aligns with the <Name> or <Project Type tag> from the business logic? Sorry, I can't remember, and we're not clear here.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="XSD/project_explorer.xsd">
  <Name>VBET</Name>
  <ProjectType>VBET</ProjectType>
  <Node xpathlabel="Name">

If I understand correctly @MattReimer "Programs" are going away with release of v 3.0 of warehouse? If so, it seems like an opportune time to specify this in a slightly more future proof way.

I can understand that you may not want versions of business logic to align with versions of a release. It is likely there will be far more releases than versions of business logic. It is more like each release specifies which version of the business logic it uses. The idea of a "Latest" may be helpful, but the idea of "Final" is naive. Thoughts?

[MattReimer]

Ok so. Some notes:

• The name of the businesslogic file must match what is in the <ProjectType>VBET</ProjectType> tag exactly. It is case sensitive. This means that VBET_FINAL.xml will not work unless VBET_FINAL is the name of your project type.

  That has other implications for Symbology so I think we should not be changing the project type in this way or using it as a way to differentiate versions of the same tool.

• Multiple deployed versions of businesslogic for a single project type is currently not allowed. The V1 or V2 you might see are only in regards to the version of the XML itself (think old warehouse Vs. new warehouse); Not to distinguish between two versions of the same tool.

• Developers who are working on a tool or other individuals who need a different businesslogic are welcome to use a different <PROJECT_NAME>.xml in any of the locations that RAVE looks for business logic files.

• the link above is for ArcRave that can have business logic in several places. For QRave the places it looks for business logic are much simpler.

  1. next to the project.rs.xml file. I would use this 90+ % of the time. The only danger here is that in the current iteration of the CLI there is a risk that the custom businesslogic will be uploaded accidentally with the project. I have deemed this an acceptable risk.

  2. In the resource folder. I would not use this because when the XML syncs from the web again your custom business logic is overwritten. There are workflows around this but it's not the safest and so I list it only for completeness.

---

Ok, now that's out of the way let's get speculative. I will preface all of this:

while I like the idea of linking tools and businesslogic versions the risk of adding this complexity and making the system error-prone and unusable to our tool developers is very real so all of this is just pie-in-the-sky for now.

1. Businesslogic could have version gates

<Node 
label="Outputs" 
xpath="Realizations/whatever" 
minVersion="1.1.2" maxVersion="2.1.3" />

This would create a choose-your-own adventure inside our businesslogic where, if minVersion or maxVersion, (both optional BTW), are set we choose whether or not to go down that path.

Pro

• One businessLogic file to rule them all. Nothing changes in RiverscapesXML except adding minVersion and maxVersion to the spec.

• Whenever a new version of the tool breaks something just create a new gate using copy and paste and change the new DOM node:

<node label="Outputs" maxVersion="2.1.3" >
   /* Here's the OLD way */
</node>
<node label="Outputs" minVersion="1.1.2" >
  /* Here's the NEW way. */
</node>

• Would work with WebRave (not out of the box though)

Con

• Every RAVE needs to be updated with this new way to traverse the DOM. Not a huge amount of work but it needs to be identical across all of them.

• Testing this gets really gnarly because it means you ideally need to keep at least one version of VBET project for every path mentioned in the businesslogic. You need to think about versions other than the one you're developing for so you don't break others' experiences.

• It's pretty easy to write yourself into a corner with this. Our DOMs can get pretty spidery and you'd need to be aware of more than just the level of DOM you're working at:

<node minVersion="1.1.2" >
    /* potentially many lines of XML here */

    <node minVersion="1.1.1" >
        /* ERROR: This path is impossible */
    </node>

</node>

2. Versioned BusinessLogic files.

In this version we have actually different files that we publish for different versions of the tools.

Pros

• Cleaner and simpler to understand (in one sense) for businesslogic writers. Open the file I want to edit and don't worry about trampling anyone else's versions. New version of the tool? Cool, copy the businesslogic to a new file and make your changes.

Cons

• We'd need to change how the RiverscapesXML repo is structured and how we publish it.
• The net_sync functions would be doing more work and syncing a lot more files
• How we name these files is TBD but that presents a bit of a challenge to choose a good naming scheme where intent is clear.
• Breaks the method we have for looking for and finding businesslogic that matches the project we are looking at. Lots of questions here.

3. Git tagging or ref hash tagging of version tools

In this example we make the git tag or hash of the tool linked in some way to the git tag or hash of the business logic.

this 100% breaks our publishing method for RiverscapesXML and so I won't entertain this at all but mention it here for completeness.

[joewheaton]

Thanks so much for this @MattReimer. This is a really helpful explanation, reminder and speculation about things we could do. I like the idea of version gates, and I like how you've laid out pros and cons for these. I think when we get to discussions of documentation (@jtgilbert and @philipbaileynar) and updates to RAVE associated with this we can take your notes and use that to help us. The rest of this seems like something that is > 3.X Warehouse release, but it is good to start thinking about here.