refactor: promotion mechanisms --> promotion directives

[krancour]

Current State

Up to now, the Promotion process for each Stage employs opinionated "promotion mechanisms."

These fall into two general categories:

1. Git based changes
2. Argo CD based changes

All git-based changes are applied first then all Argo CD based changes are applied.

All mechanisms (of either of these general types) basically work by matching to a piece of Freight and then carrying out some opinionated process. In plain English: "When I see one of these do this with it."

Why This Needs to Change

There are a number of compelling reasons to transition away from this approach, toward something else.

• Upcoming work:
  • Notification hooks
  • Manual approval hooks
  • File copy
  • Pluggable promotion mechanisms
  • More options for where results are written to (e.g. OCI registry instead of Git repo branch?)
• Outlying use cases may be poorly served by the opinions of the existing promotion mechanisms

All of these point to a need to define promotion processes at a more granular level.

Promotion Directives

An analogy can be made to either the directives in a Dockerfile or the steps in a GitHub Actions job.

If we transition to promotion processes being defined as a series of ordered steps, it creates an easier path to addressing everything discussed in the previous section.

Benefits:

• A framework for execution of generic promotion directives will support third-party integrations for:
  • Notifications
  • Manual approvals
  • Configuration management tools
  • Storage
• Ordered steps permit more finely-grained control over complex processes:
  • Where in the process should users be notified?
  • Where in the process are manual approvals required?
  • Need to do something unusual? No problem.

Technical Considerations

• Just as with a Docker build or a GitHub Actions job, we will require some sort of context for the process.
• We will required a clearly defined interface for directives. Non-exhuastively, this will need to account for:
  • Directive input/output
  • Amending persistent context (because long-running promotions will require many reconciliations to complete)
  • Amending process and/or directive-specific status (again, because some promotions will require many reconciliations to complete)
  • Access to repository credentials
  • Access to credentials for third-party services. e.g. A directive that sends notifications to slack will require some sort of credentials.
  • Clearly defined hooks for polling third-party services for status. e.g. Is a PR merged yet? Closed?
  • Clearly defined hooks for receiving status updates from third-party services. e.g. Be notified a PR was merged/closed.
  • Clearly defined directive results:
    • Success / continue to the next step
    • Sleep the process (enqueue for re-reconciliation at a later time)
    • Unrecoverable error
    • Recoverable error

Plan

Due to the breaking changes that this will introduce and the immediate need for these changes as an enabler of future work, we are scheduling this work for v0.9.0. Due to the epic nature of this issue, it will constitute the primary theme of that release.