rename Freight's "qualified" field to "verifiedIn"; add "approvedFor" field

[krancour]

"Qualified" can be a misleading term. It makes sense or it doesn't, depending how you look at it...

Pieces of Freight become qualified in a Stage when they first become healthy in that Stage.

A piece of Freight becomes available to a Stage when it's been qualified in any of that Stage's upstream Stages...

But another way to say "available to Stage x" would be "qualified for Stage x."

Qualified in vs qualified for -- two distinctly different semantic meanings.

Kargo uses the former, but anyone could be forgiven for thinking it is the latter.

Is this asking for trouble? Is there a less ambiguous way to articulate the semantics we're using?

[krancour]

@jessesuen and I spoke about this today in the context of users being able to manually add a qualification, which would be helpful in the case of, for instance, approving a hotfix for production.

In such a case, one would want to say, "this freight is qualified for production" rather than saying, "this freight is qualified in staging," because it didn't.

We decided that it would be sensible to maintain two separate lists of qualifications for each freight. Where it was qualified in and where it is qualified for. The second list would only ever be amended in the case of a manual qualification.

Determining whether a piece of freight can move into a given stage then becomes a question of, "did it qualify upstream from the target stage OR was it manually qualified for the target stage?" These semantics also go a long way toward clearning up the confusion mentioned in the OP here.

NB: One thing we don't want to do is update the "qualified for" list in the normal, happy path. We would not, for instance, want to say "this freight is qualified for prod because it worked out in staging," because the stage DAG could be re-ordered at any time and then it may no longer be true that qualifying in staging qualifies freight for prod.

[krancour]

I've been working on this for a while and keep finding that the nuanced difference between "qualified in" and "qualified for" keep tripping up even myself. I am not comfortable asking users to keep that straight!

@rbreeze and I put our heads together and decided things felt straightforward if we named the two lists verifiedIn (Stages where as piece of Freight has been verified through the regular process) and approvedFor (Stages for which a piece of Freight was manually approved/fast-tracked).

We both recognized that "approved" is a term we may wish to repurpose for something else as we continue along, but if and when that need is recognized, refactoring this should be pretty straightforward.