Documentation
¶
Overview ¶
Package stack models a feature that spans several repositories: a set of merge requests with a dependency order between them.
A stack is not a chain of git branches. Each merge request is cut from its own repository's default branch; what the stack records is the order they must merge in, so an SDK change lands before the API change that needs it.
Index ¶
- Variables
- func Dir(configDir string) string
- type Item
- type Stack
- func (s *Stack) Blockers(id string, states map[string]State) []string
- func (s *Stack) Dependents(id string) []Item
- func (s *Stack) Find(id string) (Item, bool)
- func (s *Stack) Layers() ([][]Item, error)
- func (s *Stack) Next(states map[string]State, greenStatus string) (Item, bool)
- func (s *Stack) Order() ([]Item, error)
- func (s *Stack) Progress(states map[string]State) (merged, total int)
- func (s *Stack) Ready(id string, states map[string]State, greenStatus string) bool
- func (s *Stack) Save(dir string) error
- func (s *Stack) StatusOf(id string, states map[string]State, greenStatus string) Status
- func (s *Stack) Summary(states map[string]State, greenStatus string) map[Status]int
- func (s *Stack) Validate() error
- type State
- type Status
Constants ¶
This section is empty.
Variables ¶
var ( ErrCycle = errors.New("the stack has a dependency cycle") ErrUnknownDep = errors.New("the stack depends on an item that does not exist") ErrDuplicateID = errors.New("the stack has two items with the same id") )
Errors returned when a stack does not describe a valid graph.
StatusOrder is the order a summary reads in.
Functions ¶
Types ¶
type Item ¶
type Item struct {
ID string `yaml:"id"`
Profile string `yaml:"profile,omitempty"`
Host string `yaml:"host"`
Repo string `yaml:"repo"`
MR int `yaml:"mr"`
DependsOn []string `yaml:"depends_on,omitempty"`
}
Item is one merge request in a stack.
Profile is per item, not per stack: a feature can legitimately span two identities, or two providers, and the profile is what tells them apart when both live on the same host.
type Stack ¶
Stack is a named set of merge requests and the edges between them.
func LoadAll ¶
LoadAll reads every stack in a directory, sorted by name. A missing directory yields no stacks and no error: not having any is normal.
func (*Stack) Dependents ¶
Dependents lists the items that depend directly on id — the ones that may need rebasing once it merges.
func (*Stack) Layers ¶
Layers groups the items by how deep they sit in the dependency graph: layer 0 depends on nothing, layer 1 on layer 0, and so on.
It is the shape the graph is drawn in — everything in a layer can merge in parallel once the layer before it has landed, which is the thing a reader wants to see. Items within a layer keep their declared order.
func (*Stack) Next ¶
Next is the item to merge now: the first in dependency order that is ready.
There is deliberately only ever one. Merging two at once means the second was resolved against a tree the first has since changed.
func (*Stack) Order ¶
Order returns the items in an order that satisfies every dependency: nothing appears before something it depends on. Items that do not depend on each other keep their declared order, so the file stays readable.
It reports ErrCycle, ErrUnknownDep or ErrDuplicateID rather than guessing.
func (*Stack) Ready ¶
Ready reports whether an item can be merged right now: every dependency has merged, the provider considers it mergeable, and its own pipeline is green.
A missing pipeline does not block: plenty of repositories have no CI.
func (*Stack) StatusOf ¶
StatusOf classifies one item.
Blocked outranks waiting: an item whose dependency has not merged is not waiting for its own CI in any useful sense, and saying "blocked on sdk" is more use than "waiting".
type State ¶
type State struct {
Merged bool
Closed bool
Mergeable bool
// Pipeline is the CI status of the item's own branch, using the
// forge.Status* vocabulary. Empty means "no pipeline".
Pipeline string
}
State is what the provider currently says about one item. The UI fills this in; the stack itself performs no I/O.
type Status ¶
type Status string
Status is where one item stands, as a single word.
It exists so the list, the graph and the merge gate say the same thing about the same item: three places deciding separately what "ready" means is three chances to disagree.
const ( Merged Status = "merged" Ready Status = "ready" Waiting Status = "waiting" // its own CI is not green yet Blocked Status = "blocked" // something it depends on has not merged Closed Status = "closed" Stuck Status = "stuck" // nothing blocking it, but the provider refuses Unknown Status = "unknown" )
The states an item can be in, in the order a stack moves through them.
func SortedStatuses ¶
SortedStatuses is the statuses present in a summary, in reading order.
Source Files