Proposal Tracking

[GeorgeMac]

The cup API should have some mechanism for tracking the state of resource change proposals.

When a Put or Delete action occurs, it results in a proposal to a target Source destination.
For the git type sources with a backing SCM, this manifests as a Pull or Merge Request.

We should tie the state of these proposals back into the resource API somehow.
For example, we could replicate the concept of the Status API in Kubernetes land.
Each resource could have a status on it. This status would contain entries for each currently proposed change.

Additionally, we should have an endpoint for all proposed changes. So that there is a central way to discover all open requests.
This is potentially useful for downstream tooling to present.

I suspect that for a first pass, we might be able to rely entirely on the SCM as the source of truth for this state. This would likely be enough to get to an MVP. Something which demonstrates the feature, so we can understand if it actually provides value.
This has the added benefit that it requires no extra dependencies to run cup. Meaning that, for example, just having a GitHub account and repository is enough to experiment with running it yourself.

Down the line, I suspect that this might come with its own scalability problems.
Each cup instance will have to do some tricks to stash relevant correlation state in corners of the SCM APIs.

Storing State

The kinds of questions we might want to ask with this data is:

• Does this resource have an open proposal?
• How many open proposals are there for a single resource?
• What is being proposed by each proposal?
  • Is just PUT vs DELETE enough?
• Is the proposal going through some CI process and what is the status of that?
• Has the proposal got requested changes on it?

Individual Resource State

In order to support e.g. a Status section for resources, we will need to be able to correlate open proposals (PRs, MRs etc) with a particular instance of a resource (kind, namespace and name). You could imagine e.g. an API like that of k8s status APIs:

GET /apis/{ group }/{ version }/namespaces/{ namespace }/{ kind.plural }/{ name }/status

The identifying metadata in this path would need to be correlated with some additional metadata in the proposal.

Some potential locations we can stash this kind of metadata is:

• PR title
• commit message (header and/or body)
• PR Description

The outcome of this decision also effects the next decision around listing all open proposals.

Listing all open proposal state

It will likely become valuable to list all open proposal statuses.
Depending on how we choose to stash state, the complexity of this operation changes.
If it is simply in the PR title, then we can rely solely the SCM list API.
However, if it is nested insider commit metadata or PR descriptions, then subsequent API requests are required to manifest this information.