Documentation
¶
Overview ¶
Package importplan is the vocabulary an import shares when it asks before it replaces anything (ADR-0467): how an artifact an import carries compares with the one this server holds, what the caller decided for those that differ, and what became of each.
The rule it encodes is one sentence: an import writes what is new, leaves what is unchanged, and writes over work done on the server only when the caller said so. Work done on a server is not replaced by an import nobody looked at, and the same import run twice changes nothing the second time.
Telling work done on the server from an import that moved on takes a third version: the one the last import brought, remembered per artifact as a hash (its base). An artifact still as the last import left it, and different in this one, is behind and simply taken; one edited here while the import still carries what it carried last time is ahead and simply kept. Only an artifact both sides moved — or one no import ever brought, so there is no base to tell by — is asked about.
Index ¶
Constants ¶
const ( New = "new" Unchanged = "unchanged" // Changed is an artifact both sides moved since the last import, or one this // server holds otherwise and no import ever brought. It is decided. Changed = "changed" // Behind is an artifact this server still holds as the last import brought it, // and that this import brings newer. It is taken unless the caller keeps it. Behind = "behind" // Ahead is an artifact edited on this server since the last import, which this // import brings as it did last time. It is kept unless the caller replaces it. Ahead = "ahead" // Elsewhere is an artifact another existing application holds. An import never // takes it unasked: only a ref named under adopt moves it into the importing // application, and the caller needs the editor role on the application it leaves. // Unadopted, it stops the import like a change nobody decided. Elsewhere = "elsewhere" // Gap is a capability or value stream an import needs and this server's map does // not have (ADR-0528). The map is the // organisation's, so an import never files one silently: the caller adopts the // bundle's proposal, maps the key onto one the map has, or omits it. Undecided, it // stops the import like a change nobody decided. Gap = "gap" // Linked is a proposal for a key the map already has: the import files what it // brings under that key and never writes over the map's record. Compared says // whether the proposal reads like the record. Nothing to decide. Linked = "linked" // Owned is a record only imports write — an application's realizations — which an // import replaces as the tree states it. Nothing to decide. Owned = "owned" )
How an artifact an import carries compares with this server's.
const ( Created = "created" Updated = "updated" Kept = "kept" Undecided = "undecided" // Mapped is a gap the caller settled with a key the map already has: what the // bundle named under its own key is filed under that one, and nothing is created. Mapped = "mapped" // Omitted is a gap the caller left out: nothing is created, and what named it is // not filed. Omitted = "omitted" )
What became of an artifact, or would under the decisions given.
const GapProblem = "" /* 167-byte string literal not displayed */
GapProblem is what an import stopped for an undecided gap says of it.
const UndecidedProblem = "differs from this server's; name it under overwrite to replace it or under keep to leave it"
UndecidedProblem is what an import stopped for an undecided artifact says of it.
Variables ¶
This section is empty.
Functions ¶
func Classify ¶
Classify is how an artifact compares, from the hashes of this server's version, the import's and the base — the version the last import brought, "" when none did.
Types ¶
type Artifact ¶
type Artifact struct {
Ref string `json:"ref"`
Name string `json:"name,omitempty"`
Status string `json:"status"`
Outcome string `json:"outcome"`
// HeldBy names the application an Elsewhere artifact belongs to, {id, name} —
// only for a caller who may see that application, and absent otherwise.
HeldBy *Holder `json:"heldBy,omitempty"`
// Compared is how an Elsewhere artifact's content compares with the import's
// (new is impossible; unchanged or changed), so one dialog can ask both whether
// to take it and, if its content differs, which version to keep.
Compared string `json:"compared,omitempty"`
// Adopted says the artifact moves into the importing application from the one
// that held it, as the caller decided under adopt.
Adopted bool `json:"adopted,omitempty"`
// Proposed says a gap comes with the bundle's proposal, which adopt files in the
// map; a gap without one can only be mapped or omitted.
Proposed bool `json:"proposed,omitempty"`
// MappedTo is the existing key a gap was mapped onto.
MappedTo string `json:"mappedTo,omitempty"`
// Detail says in words why an artifact is planned as it is, where the status alone
// does not: a proposal for a key the map has is never written over the map's record.
Detail string `json:"detail,omitempty"`
}
Artifact is one artifact of an import. Ref names it as the overwrite and keep lists do — kind:id, such as process:onboarding or product:laptop.
type Decisions ¶
type Decisions struct {
// DryRun asks for the plan alone: nothing is written.
DryRun bool
// Overwrite and Keep name artifacts by ref.
Overwrite, Keep map[string]bool
// OverwriteAll and KeepAll stand for every changed artifact the other list does
// not name.
OverwriteAll, KeepAll bool
// Adopt names, by ref, the artifacts another application holds that the caller
// takes into the importing one. There is no * for it: moving an artifact out of
// somebody's application is decided artifact by artifact.
Adopt map[string]bool
// Map settles gaps with keys the map already has: ref (capability:<key>) to the
// existing key.
Map map[string]string
// Omit names gaps left out; OmitAll leaves out every gap no other decision names.
Omit map[string]bool
OmitAll bool
}
Decisions is what the caller decided for the artifacts that differ.
func Parse ¶
Parse reads ?dryRun=, ?overwrite=, ?keep=, ?adopt=, ?map= and ?omit=. Each list is refs separated by commas, a parameter may repeat, and * stands for every changed artifact the other list does not name. A ref in both lists, or * in both, contradicts itself and is refused. ?map= takes ref=key pairs, such as capability:konten=identitaet; ?omit=* leaves out every gap no other decision names.
func (Decisions) GapOutcome ¶ added in v0.23.0
GapOutcome is what becomes of a gap under these decisions: Created when the caller adopts the bundle's proposal, Mapped (with the key) when it names an existing key, Omitted when it leaves the gap out, Undecided otherwise. A ref named under adopt with no proposal to adopt is the caller's mistake, reported by the importer.
func (Decisions) Outcome ¶
Outcome is what becomes of an artifact of a status under these decisions. A ref named in a list wins over everything else. Behind is taken and ahead kept without one, and * decides only what is changed: overwrite=* never replaces work done only here, and keep=* never holds back what only the import moved.
Source Files