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
| API | intelligence.etorm.com/v1alpha1 |
| Resource | changeproposals (cluster-scoped inside its cluster) |
| Short names | chgprop |
| Available in | project clusters only |
| Status | written 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
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
swarmRef | object | yes | The swarm the proposing agent belongs to. | ||
swarmRef.name | string | yes | length 1 to 63 | Name of the Swarm. | |
kind | string (one of) | yes | GateFix, DependencyBump, Docs, Chronicle | GateFix (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. | |
repository | object | yes | The repository to change; it must be one of the swarm's changeRepositories. | ||
repository.cluster | string | yes | length 1 to 63 | The project that holds the Repository. | |
repository.name | string | yes | length 1 to 63 | Name of the Repository. | |
title | string | yes | length 1 to 120 | The change request's and the ticket's title. | |
description | string | up to 4000 characters | What was found and why the change is right. Written by a model: a claim, not a fact. | ||
files | list of object | up to 20 items | The files to put or delete. Empty only for a GateFix that is just a ticket. | ||
files[].path | string | yes | length 1 to 200 | Path in the repository, relative, no `..`. | |
files[].action | string (one of) | yes | put, delete, section | put writes the whole file; delete removes it; section adds a new `## ` section ahead of the existing ones (PROGRESS.md, Chronicle only). | |
files[].content | string | up to 65536 characters | The whole new content of a put, or the text of a section. | ||
bumps | list of object | up to 50 items | For a DependencyBump: each crate and its versions; the new version must be a semver-compatible update. | ||
bumps[].crate | string | yes | up to 64 characters | The crate's name. | |
bumps[].from | string | yes | up to 32 characters | The version it has now. | |
bumps[].to | string | yes | up to 32 characters | The version it moves to. | |
ticket | object | The ticket (Forge card) to make; the swarm's ticketBoard says where. | |||
ticket.cause | string | up to 2000 characters | The likely cause. | ||
ticket.owner | string | up to 100 characters | The likely owner (a name taken from the failing commit's author or the area), as a label: it assigns nothing. | ||
ticket.run | string | up to 63 characters | For a GateFix: the failed Run. | ||
decision | object | A person's decision. Rejected stops the proposal. | |||
decision.state | string (one of) | Approved, Rejected | Approved or Rejected. | ||
decision.reason | string | up to 500 characters | Why, written by the person. |
Status
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
phase | string | Proposed, Planned (plan mode: recorded, nothing made), Opened (change request made), Rejected or Failed. | |||
fileCount | integer | Files in the proposal. | |||
plan | list of object | What would be written: path, action, size and digest of each file. | |||
plan[].path | string | Path. | |||
plan[].action | string | put or delete. | |||
plan[].bytes | integer | Size of the content. | |||
plan[].sha256 | string | SHA-256 of the content, hex. | |||
branch | string | The branch made, `agents/<swarm>/<proposal>`. | |||
headCommit | string | Its commit. | |||
changeRequestRef | object | The change request opened. | |||
changeRequestRef.name | string | Name of the ChangeRequest. | |||
cardRef | object | The ticket opened. | |||
cardRef.name | string | Name of the Card. | |||
reason | string | Why it was rejected, failed or stayed a plan. | |||
conditions | list of object | Detailed state. | |||
conditions[].type | string | Aspect. | |||
conditions[].status | string | True or False. | |||
conditions[].reason | string | Machine-readable reason. | |||
conditions[].message | string | Human-readable detail. |
Columns in listings
| Column | From |
|---|---|
| Kind | .spec.kind |
| Repository | .spec.repository.name |
| Files | .status.fileCount |
| Phase | .status.phase |
| Change | .status.changeRequestRef.name |