software.change/1

Deliver a change to a software system: implement it, verify the current implementation revision, merge it under authority, release and deploy it, and accept it once its objective is realized; or close it declined, superseded or abandoned on an explicit decision, or rolled back on a complete rollback result. A case fixes its risk, which selects the obligations that apply, and its change kind, which selects whether a regression must be reproduced before the implementation is edited, and whether its regression test must fail on its first run, before the implementation is first changed; and whether it affects a security boundary, in which case the implementation is verified only once a principal other than the implementer approved its security review. A deployment is healthy only on an observation at most 30 minutes old.

• Id: software.change
• Revision: 1
• Source: protocols/software-change/1.yaml

Dependency graph

Which actions may produce which evidence, which claims that evidence establishes, and which outcomes and obligations rest on those claims. Hover or focus a node to trace what it rests on.

Protocol · revision 1

software.change/1

Deliver a change to a software system: implement it, verify the current implementation revision, merge it under authority, release and deploy it, and accept it once its objective is realized; or close it declined, superseded or abandoned on an explicit decision, or rolled back on a complete rollback result. A case fixes its risk, which selects the obligations that apply, and its change kind, which selects whether a regression must be reproduced before the implementation is edited, and whether its regression test must fail on its first run, before the implementation is first changed; and whether it affects a security boundary, in which case the implementation is verified only once a principal other than the implementer approved its security review. A deployment is healthy only on an observation at most 30 minutes old.

• Actions6
• Evidence kinds9
• Claims9
• Outcomes5
• Obligations6
• Claim supports claim
• Precondition, traced on hover
• Needs authority

Hover or focus a node to trace what it rests on and what rests on it. Press Enter to pin it, Escape to clear.

Case inputs

affects_security_boundary

falsetruewhether the change affects a security boundary; one that does needs an approving security review from a principal other than the implementer before its implementation is verified

change_kind

bugfixfeaturerefactorwhat the change is; a bugfix must reproduce its regression with a failing test before the implementation is edited, and its regression test must fail on its first run, before the implementation is first changed

risk

criticalelevatedstandardtrivialhow much proof the change must carry; each level applies every obligation of the level below it and one more

Protocol as text

Actions

Name	Description	Rule	Leads to
implementation.edit	change the implementation in the repository's working revision; a bugfix needs its regression reproduced first	any of claim regression.reproduced input change_kind in feature, refactor effect write	produces implementation_change
release.rollback	return to a previous release; needs authority to roll back, and invoking it earns no outcome until a rollback result says it is complete	needs release.rollback effect write	produces rollback_result
repository.inspect	read the repository	effect read	—
repository.merge	merge a revision into the repository's mainline; needs the current implementation revision verified and authority to merge, never only a connection to the repository host	claim implementation.verified needs repository.merge effect write	—
tests.run	run the tests against an implementation revision	effect read	produces regression_test_result; produces test_result
tests.write	change the tests in the repository's working revision	effect write	—

Evidence kinds

Name	Description	Rule	Leads to
build_provenance	the record of how a release was built from an implementation	—	establishes release.proven (about release)
code_review	a review of an implementation revision; its result is approved or rejected	—	establishes implementation.reviewed (approved about implementation)
implementation_change	the record that the implementation was changed, moving it to a new revision	—	establishes regression.shown_first (after regression_test_result about implementation)
objective_observation	an observation of whether the intent's objective is met; its result is satisfied or unsatisfied	—	establishes objective.realized (satisfied about intent)
operational_observation	an observation of the running system; its result is healthy or unhealthy, and it applies for 30 minutes after it is observed, after which it no longer says anything	—	establishes deployment.healthy (healthy about deployment)
regression_test_result	the result of running a bugfix's regression test against an implementation revision; its result is pass or fail	—	establishes regression.reproduced (first fail about implementation); establishes regression.shown_first (before implementation_change about implementation); establishes regression.shown_first (first fail about implementation)
rollback_result	the result of returning a release to the one before it; its result is complete or partial	—	—
security_review	a review of an implementation revision's effect on a security boundary; its result is approved or rejected	—	establishes security.reviewed (approved about implementation, independent on different_principal)
test_result	the result of running tests against an implementation revision; its result is pass or fail	—	establishes implementation.verified (pass about implementation); establishes regression.reproduced (fail about implementation); establishes tests.pass (pass about implementation)

Claims

Name	Description	Rule	Leads to
deployment.healthy	the deployment is running healthily	evidence = healthy: operational_observation	requires accepted; requires health.required
implementation.reviewed	the current implementation revision is reviewed	evidence = approved: code_review	requires review.required
implementation.verified	the current implementation revision is verified: its tests pass and, when the change affects a security boundary, it is security reviewed	all of any of claim security.reviewed input affects_security_boundary in false evidence = pass: test_result	supports release.proven; gates repository.merge
objective.realized	the intent's objective is met	evidence = satisfied: objective_observation	requires accepted
regression.reproduced	the regression a bugfix repairs is reproduced: a test has failed on the current implementation revision, or the first run of the regression test, on any revision of the implementation, failed	any of evidence = fail: test_result first evidence = fail: regression_test_result about implementation	gates implementation.edit
regression.shown_first	the regression test failed first, before the implementation was first changed: the first regression test result about the implementation failed, and it was observed before the implementation's first change	all of evidence regression_test_result before implementation_change about implementation first evidence = fail: regression_test_result about implementation	requires red_first.required
release.proven	the current implementation revision is verified and the current release revision carries build provenance; nothing here ties that release to the verified implementation revision	all of claim implementation.verified any evidence: build_provenance	requires accepted; requires provenance.required
security.reviewed	the current implementation revision's security review is approved by a producer the case lists as another principal than the implementer	evidence = approved: security_review	supports implementation.verified; requires security_review.required
tests.pass	the tests pass for the current implementation revision	evidence = pass: test_result	requires tests.required

Outcomes

Name	Description	Rule	Leads to
abandoned	the case closed because the change was explicitly abandoned without reaching any planned outcome	—	—
accepted	the case closed with its result accepted; needs the release proven, the deployment healthy and the objective realized	all of claim deployment.healthy claim objective.realized claim release.proven	—
declined	the case closed because the change was explicitly declined; needs no implementation	—	—
rolled_back	the case closed with its release rolled back; needs a rollback result about the current release revision that says the rollback is complete	evidence = complete: rollback_result	—
superseded	the case closed because another change explicitly superseded it	—	—

Obligations

Name	Description	Rule	Leads to
health.required	the deployment is healthy; applies at critical risk	applicable when input risk in critical claim deployment.healthy	—
provenance.required	the release is proven; applies at elevated risk and above	applicable when input risk in critical, elevated claim release.proven	—
red_first.required	the regression test failed on its first run, before the implementation was first changed; applies to a bugfix, at every risk	applicable when input change_kind in bugfix claim regression.shown_first	—
review.required	the current implementation revision is reviewed; applies at standard risk and above	applicable when input risk in critical, elevated, standard claim implementation.reviewed	—
security_review.required	the current implementation revision is security reviewed by another principal than the implementer; applies to a change that affects a security boundary, at every risk	applicable when input affects_security_boundary in true claim security.reviewed	—
tests.required	the tests pass for the current implementation revision; applies at every risk	applicable when input risk in critical, elevated, standard, trivial claim tests.pass	—

Source: protocols/software-change/1.yaml

Actions

What can be done in a case: what it needs first, which authority it requires, the class of effect it has and the evidence it may produce.

Action	Description	Precondition	Requires capability	Effect	May produce
implementation.edit	change the implementation in the repository's working revision; a bugfix needs its regression reproduced first	any of (regression.reproduced is TRUE; input change_kind is one of feature, refactor)	no authority	write	implementation_change
release.rollback	return to a previous release; needs authority to roll back, and invoking it earns no outcome until a rollback result says it is complete	none	release.rollback	write	rollback_result
repository.inspect	read the repository	none	no authority	read	no evidence
repository.merge	merge a revision into the repository's mainline; needs the current implementation revision verified and authority to merge, never only a connection to the repository host	implementation.verified is TRUE	repository.merge	write	no evidence
tests.run	run the tests against an implementation revision	none	no authority	read	regression_test_result, test_result
tests.write	change the tests in the repository's working revision	none	no authority	write	no evidence

Evidence kinds

The kinds of evidence this protocol admits. A kind with a maximum age applies for that long after a record's observed_at: evaluated at a later instant, the record is excluded as expired.

Evidence kind	Description	Applies for	Produced by	Used by claims
build_provenance	the record of how a release was built from an implementation	no limit	no action	release.proven
code_review	a review of an implementation revision; its result is approved or rejected	no limit	no action	implementation.reviewed
implementation_change	the record that the implementation was changed, moving it to a new revision	no limit	implementation.edit	no claim
objective_observation	an observation of whether the intent's objective is met; its result is satisfied or unsatisfied	no limit	no action	objective.realized
operational_observation	an observation of the running system; its result is healthy or unhealthy, and it applies for 30 minutes after it is observed, after which it no longer says anything	30m after it is observed	no action	deployment.healthy
regression_test_result	the result of running a bugfix's regression test against an implementation revision; its result is pass or fail	no limit	tests.run	no claim
rollback_result	the result of returning a release to the one before it; its result is complete or partial	no limit	release.rollback	no claim
security_review	a review of an implementation revision's effect on a security boundary; its result is approved or rejected	no limit	no action	security.reviewed
test_result	the result of running tests against an implementation revision; its result is pass or fail	no limit	tests.run	implementation.verified, regression.reproduced, tests.pass

Claims

Each claim is TRUE, FALSE or UNKNOWN, established from evidence by its predicate. Missing or stale evidence leaves a claim UNKNOWN, never FALSE.

Claim	Description	True when
deployment.healthy	the deployment is running healthily	evidence operational_observation with result healthy about deployment
implementation.reviewed	the current implementation revision is reviewed	evidence code_review with result approved about implementation
implementation.verified	the current implementation revision is verified: its tests pass and, when the change affects a security boundary, it is security reviewed	all of (any of (security.reviewed is TRUE; input affects_security_boundary is one of false); evidence test_result with result pass about implementation)
objective.realized	the intent's objective is met	evidence objective_observation with result satisfied about intent
regression.reproduced	the regression a bugfix repairs is reproduced: a test has failed on the current implementation revision, or the first run of the regression test, on any revision of the implementation, failed	any of (evidence test_result with result fail about implementation; the first regression_test_result about implementation is fail)
regression.shown_first	the regression test failed first, before the implementation was first changed: the first regression test result about the implementation failed, and it was observed before the implementation's first change	all of (the first regression_test_result before the first implementation_change, both about implementation; the first regression_test_result about implementation is fail)
release.proven	the current implementation revision is verified and the current release revision carries build provenance; nothing here ties that release to the verified implementation revision	all of (implementation.verified is TRUE; evidence build_provenance about release)
security.reviewed	the current implementation revision's security review is approved by a producer the case lists as another principal than the implementer	evidence security_review with result approved about implementation, from a producer independent on different_principal
tests.pass	the tests pass for the current implementation revision	evidence test_result with result pass about implementation

Obligations

What must be done before a case can be complete, and what discharges it. An obligation stays open until its predicate is TRUE; its predicate being UNKNOWN does not discharge it.

Obligation	Description	Applies when	Discharged when
health.required	the deployment is healthy; applies at critical risk	input risk is one of critical	deployment.healthy is TRUE
provenance.required	the release is proven; applies at elevated risk and above	input risk is one of critical, elevated	release.proven is TRUE
red_first.required	the regression test failed on its first run, before the implementation was first changed; applies to a bugfix, at every risk	input change_kind is one of bugfix	regression.shown_first is TRUE
review.required	the current implementation revision is reviewed; applies at standard risk and above	input risk is one of critical, elevated, standard	implementation.reviewed is TRUE
security_review.required	the current implementation revision is security reviewed by another principal than the implementer; applies to a change that affects a security boundary, at every risk	input affects_security_boundary is one of true	security.reviewed is TRUE
tests.required	the tests pass for the current implementation revision; applies at every risk	input risk is one of critical, elevated, standard, trivial	tests.pass is TRUE

Outcomes

The legitimate terminal interpretations of a case, and what each requires.

Outcome	Description	Requires
abandoned	the case closed because the change was explicitly abandoned without reaching any planned outcome	decision explicitly_abandoned
accepted	the case closed with its result accepted; needs the release proven, the deployment healthy and the objective realized	all of (deployment.healthy is TRUE; objective.realized is TRUE; release.proven is TRUE)
declined	the case closed because the change was explicitly declined; needs no implementation	decision explicitly_declined
rolled_back	the case closed with its release rolled back; needs a rollback result about the current release revision that says the rollback is complete	evidence rollback_result with result complete about release
superseded	the case closed because another change explicitly superseded it	decision explicitly_superseded

Artifacts

The things whose revisions evidence is bound to.

Artifact	Description
deployment	a release running in an environment
implementation	a revision of the code that realizes the plan
intent	what the change is meant to achieve
plan	the intended steps toward the intent
release	a versioned, deployable unit of the system
system_specification	the specified behaviour of the system concerned

Case inputs

What a case fixes when it opens: each input takes one of the values listed, and is never UNKNOWN.

Input	Description	Values
affects_security_boundary	whether the change affects a security boundary; one that does needs an approving security review from a principal other than the implementer before its implementation is verified	false, true
change_kind	what the change is; a bugfix must reproduce its regression with a failing test before the implementation is edited, and its regression test must fail on its first run, before the implementation is first changed	bugfix, feature, refactor
risk	how much proof the change must carry; each level applies every obligation of the level below it and one more	critical, elevated, standard, trivial

Independence dimensions

What an evidence match may demand of a record's producer (independent_on). The case lists, for each producer, the dimensions on which it is independent of the case's work; a match that demands a dimension reads only records whose producer the case lists on it. A record that fails the demand neither establishes nor contradicts the match, so a match only such records would decide is UNKNOWN.

Dimension	Description
different_agent_run	the producer is another agent run than the one that did the case's work
different_principal	the producer is another principal than the one who did the case's work