Documentation
¶
Index ¶
- Constants
- func ChangedFields(stamp Stamp, operation Operation, names ...string) []string
- func CheckWrite(operation Operation, stamp Stamp, live string, names []string, label string) (bool, error)
- func Digest(values ...any) string
- func Edited(stamp Stamp, live string) bool
- func FieldDigests(operation Operation, names ...string) map[string]string
- func OrphanWarnings(labels map[string]string, planned []Operation) []string
- func ResolveReferences(value string, resolved map[domain.ItemID]RemoteRef) (string, error)
- func UniqueSorted(values []string) []string
- type Adapter
- type Operation
- type OperationResult
- type Plan
- type PlanInput
- type PublishedIssue
- type Receipt
- type RemoteRef
- type Stamp
- type SyncRequest
- type Syncer
Constants ¶
const ( ActionCreateIssue = "create_issue" ActionReuseIssue = "reuse_issue" ActionUpdateIssue = "update_issue" ActionLinkIssues = "link_issues" ActionUnlinkIssues = "unlink_issues" )
Operation actions shared by adapters and apply.
const SchemaVersion = "v1"
Variables ¶
This section is empty.
Functions ¶
func ChangedFields ¶ added in v0.21.6
ChangedFields lists the named fields whose digest differs from a stamp. A stamp without source digests predates sync, so every field counts as changed and the first sync rewrites the issue.
func CheckWrite ¶ added in v0.21.6
func CheckWrite(operation Operation, stamp Stamp, live string, names []string, label string) (bool, error)
CheckWrite decides whether an update still needs to write. It reports written when the stamp already records this operation's write, as on a retry of an update that landed before apply recorded it. Otherwise it refuses an issue that changed after the plan read it: --force covers only the edits the plan saw.
func Digest ¶ added in v0.21.6
Digest hashes values into a stable hex string. Maps hash identically whatever their key order, because encoding/json sorts map keys.
func Edited ¶ added in v0.21.6
Edited reports whether a remote issue may have changed since devex last wrote it. An issue stamped before sync existed carries no source digests and counts as unedited. A stamp without a live digest records a write devex could not read back, or a stamp damaged by hand, so it counts as edited.
func FieldDigests ¶ added in v0.21.6
FieldDigests digests each named field of an operation.
func OrphanWarnings ¶ added in v0.21.6
OrphanWarnings names published issues whose markers the bundle no longer plans. labels maps each published marker to its issue label.
func ResolveReferences ¶
func UniqueSorted ¶ added in v0.16.4
UniqueSorted returns the distinct non-empty values in sorted order, so label sets stay stable across plans and therefore keep the plan digest stable.
Types ¶
type Adapter ¶
type Adapter interface {
ID() string
Plan(context.Context, PlanInput, config.Target) ([]Operation, []string, error)
// Resolve reports which of the given operations already exist remotely, keyed by
// idempotency key. Apply calls it once with the operations a receipt has not already
// accounted for, so an adapter can search for exactly the work that remains.
Resolve(context.Context, config.Target, *Plan, []Operation) (map[string]RemoteRef, error)
Execute(context.Context, config.Target, Operation, map[domain.ItemID]RemoteRef) (RemoteRef, error)
}
type Operation ¶
type Operation struct {
ID string `yaml:"id" json:"id"`
Action string `yaml:"action" json:"action"`
ItemID domain.ItemID `yaml:"item_id" json:"item_id"`
DependsOn []string `yaml:"depends_on,omitempty" json:"depends_on,omitempty"`
IdempotencyKey string `yaml:"idempotency_key" json:"idempotency_key"`
Summary string `yaml:"summary" json:"summary"`
Fields map[string]any `yaml:"fields" json:"fields"`
}
func SyncIssue ¶ added in v0.21.6
func SyncIssue(operation Operation, issue PublishedIssue, changed []string, force bool, liveFields []string) (Operation, string)
SyncIssue turns a planned create for a published item into a reuse or an update. changed names the remote fields the update rewrites, and liveFields those whose content the live digest covers. On an edited issue, the update drops its live fields with a warning; the rest leave edits intact, so they proceed. With force, it rewrites every live field instead, so the new live digest records only what devex wrote. With nothing left to write, the item keeps its issue.
type OperationResult ¶
type Plan ¶
type Plan struct {
SchemaVersion string `yaml:"schema_version" json:"schema_version"`
ID string `yaml:"id" json:"id"`
Provider string `yaml:"provider" json:"provider"`
TargetName string `yaml:"target" json:"target"`
Target config.Target `yaml:"target_config" json:"target_config"`
DiscoveryID string `yaml:"discovery_id" json:"discovery_id"`
BundlePath string `yaml:"bundle_path" json:"bundle_path"`
SourceDigest string `yaml:"source_digest" json:"source_digest"`
PlanDigest string `yaml:"plan_digest" json:"plan_digest"`
GeneratedAt time.Time `yaml:"generated_at" json:"generated_at"`
Warnings []string `yaml:"warnings,omitempty" json:"warnings,omitempty"`
Operations []Operation `yaml:"operations" json:"operations"`
}
type PlanInput ¶ added in v0.16.5
type PlanInput struct {
WorkBreakdown *domain.WorkBreakdown
// DocumentURL resolves the discovery document for a reader, empty when no URL can be built.
DocumentURL string
// TrackingURL is the issue the discovery document links from its title, empty when absent.
TrackingURL string
}
PlanInput carries the bundle and everything derived from its surroundings that planning needs. The derived fields are best-effort: a bundle outside a GitHub checkout has no document URL, and a discovery document that links no tracking issue has no tracking URL.
type PublishedIssue ¶ added in v0.21.6
PublishedIssue is a remote issue a sync matched to a planned item. Label names it for people, such as "Jira DEVEX-2".
type Receipt ¶
type Receipt struct {
SchemaVersion string `yaml:"schema_version" json:"schema_version"`
PlanID string `yaml:"plan_id" json:"plan_id"`
Provider string `yaml:"provider" json:"provider"`
TargetName string `yaml:"target" json:"target"`
PlanDigest string `yaml:"plan_digest" json:"plan_digest"`
Status string `yaml:"status" json:"status"`
UpdatedAt time.Time `yaml:"updated_at" json:"updated_at"`
Operations map[string]OperationResult `yaml:"operations" json:"operations"`
}
type Stamp ¶ added in v0.21.6
type Stamp struct {
ID string `json:"id"`
Source map[string]string `json:"source,omitempty"`
Live string `json:"live,omitempty"`
}
Stamp records what devex last wrote to a remote issue: one digest per bundle field it wrote from, and one of the title and description as the remote stored them.
func DamagedStamp ¶ added in v0.21.6
DamagedStamp stands in for a stamp changed by hand. It records a write with no live digest, which counts as edited.
type SyncRequest ¶ added in v0.21.6
SyncRequest carries the planned operations and warnings to reconcile. Force overwrites issues edited since devex last wrote them.
type Syncer ¶ added in v0.21.6
type Syncer interface {
Sync(context.Context, config.Target, SyncRequest) ([]Operation, []string, error)
}
Syncer reconciles already-published work with a bundle. It reads the remote and returns the operations that bring it in line, with the plan's warnings revised to match them.
Source Files
Directories