Resources / ChangeProposal

ChangeProposal

A change to a repository that an automation agent of a swarm proposes: files to put or delete, a title and the reasons. It never writes to the repository itself. The platform checks the paths and sizes against the rules of the proposal's kind, records the plan, and (when the swarm is not in plan mode) makes a branch and opens an ordinary Forge change request for people and the repository's checks to judge, and a ticket card. Written by agents of the swarm only.

Overview

APIintelligence.etorm.com/v1alpha1
Resourcechangeproposals (cluster-scoped inside its cluster)
Short nameschgprop
Available inproject clusters only
Statuswritten by a controller through /status

Minimal example

apiVersion: intelligence.etorm.com/v1alpha1
kind: ChangeProposal
metadata:
  name: example
spec:
  swarmRef:
    name: "<name>"
  kind: GateFix
  repository:
    cluster: "<cluster>"
    name: "<name>"
  title: "<title>"

Spec

FieldTypeRequiredDefaultAllowedDescription
swarmRefobjectyesThe swarm the proposing agent belongs to.
swarmRef.namestringyeslength 1 to 63Name of the Swarm.
kindstring (one of)yesGateFix, DependencyBump, Docs, ChronicleGateFix (gatekeeper): a ticket for a failed gate on the default branch, with a fix when one is known. DependencyBump (maintainer): version bumps within semver. Docs (scribe): regenerated developer docs and spec fixes. Chronicle (chronicler): PROGRESS entries from merged work.
repositoryobjectyesThe repository to change; it must be one of the swarm's changeRepositories.
repository.clusterstringyeslength 1 to 63The project that holds the Repository.
repository.namestringyeslength 1 to 63Name of the Repository.
titlestringyeslength 1 to 120The change request's and the ticket's title.
descriptionstringup to 4000 charactersWhat was found and why the change is right. Written by a model: a claim, not a fact.
fileslist of objectup to 20 itemsThe files to put or delete. Empty only for a GateFix that is just a ticket.
files[].pathstringyeslength 1 to 200Path in the repository, relative, no `..`.
files[].actionstring (one of)yesput, delete, sectionput writes the whole file; delete removes it; section adds a new `## ` section ahead of the existing ones (PROGRESS.md, Chronicle only).
files[].contentstringup to 65536 charactersThe whole new content of a put, or the text of a section.
bumpslist of objectup to 50 itemsFor a DependencyBump: each crate and its versions; the new version must be a semver-compatible update.
bumps[].cratestringyesup to 64 charactersThe crate's name.
bumps[].fromstringyesup to 32 charactersThe version it has now.
bumps[].tostringyesup to 32 charactersThe version it moves to.
ticketobjectThe ticket (Forge card) to make; the swarm's ticketBoard says where.
ticket.causestringup to 2000 charactersThe likely cause.
ticket.ownerstringup to 100 charactersThe likely owner (a name taken from the failing commit's author or the area), as a label: it assigns nothing.
ticket.runstringup to 63 charactersFor a GateFix: the failed Run.
decisionobjectA person's decision. Rejected stops the proposal.
decision.statestring (one of)Approved, RejectedApproved or Rejected.
decision.reasonstringup to 500 charactersWhy, written by the person.

Status

FieldTypeRequiredDefaultAllowedDescription
phasestringProposed, Planned (plan mode: recorded, nothing made), Opened (change request made), Rejected or Failed.
fileCountintegerFiles in the proposal.
planlist of objectWhat would be written: path, action, size and digest of each file.
plan[].pathstringPath.
plan[].actionstringput or delete.
plan[].bytesintegerSize of the content.
plan[].sha256stringSHA-256 of the content, hex.
branchstringThe branch made, `agents/<swarm>/<proposal>`.
headCommitstringIts commit.
changeRequestRefobjectThe change request opened.
changeRequestRef.namestringName of the ChangeRequest.
cardRefobjectThe ticket opened.
cardRef.namestringName of the Card.
reasonstringWhy it was rejected, failed or stayed a plan.
conditionslist of objectDetailed state.
conditions[].typestringAspect.
conditions[].statusstringTrue or False.
conditions[].reasonstringMachine-readable reason.
conditions[].messagestringHuman-readable detail.

Columns in listings

ColumnFrom
Kind.spec.kind
Repository.spec.repository.name
Files.status.fileCount
Phase.status.phase
Change.status.changeRequestRef.name

All resources