fix(docs): describe state changes, values, and remote options
This commit is contained in:
parent
3935172126
commit
432ef13bb6
|
@ -89,7 +89,7 @@ Options:
|
||||||
--remote, -r [string] [required]
|
--remote, -r [string] [required]
|
||||||
```
|
```
|
||||||
|
|
||||||
Docker provides a single output stream, regardless of logger configuration. When running `graph-labes`, turning
|
Docker provides a single output stream, regardless of logger configuration. When running `graph-labels`, turning
|
||||||
the `logger.level` to `warn` or `error` will suppress log messages that could confuse `dot`.
|
the `logger.level` to `warn` or `error` will suppress log messages that could confuse `dot`.
|
||||||
|
|
||||||
### Running with Yarn
|
### Running with Yarn
|
||||||
|
|
76
docs/arch.md
76
docs/arch.md
|
@ -6,40 +6,54 @@ This guide describes the program architecture.
|
||||||
|
|
||||||
- [Architecture Guide](#architecture-guide)
|
- [Architecture Guide](#architecture-guide)
|
||||||
- [Contents](#contents)
|
- [Contents](#contents)
|
||||||
- [Purpose](#purpose)
|
- [Summary](#summary)
|
||||||
- [Label](#label)
|
- [Labels](#labels)
|
||||||
- [Flag Label](#flag-label)
|
- [Flag Labels](#flag-labels)
|
||||||
- [State Label](#state-label)
|
- [Change Sets](#change-sets)
|
||||||
- [State Value](#state-value)
|
- [State Labels](#state-labels)
|
||||||
|
- [State Values](#state-values)
|
||||||
- [State Changes](#state-changes)
|
- [State Changes](#state-changes)
|
||||||
- [Remote](#remote)
|
- [Remote](#remote)
|
||||||
- [Github Remote](#github-remote)
|
- [Github Remote](#github-remote)
|
||||||
- [Gitlab Remote](#gitlab-remote)
|
- [Gitlab Remote](#gitlab-remote)
|
||||||
- [Sync](#sync)
|
- [Sync](#sync)
|
||||||
- [Sync Issues](#sync-issues)
|
- [Sync Issues](#sync-issues)
|
||||||
- [Sync Labels](#sync-labels)
|
- [Sync Projects](#sync-projects)
|
||||||
|
|
||||||
## Purpose
|
## Summary
|
||||||
|
|
||||||
`cautious-journey` exists to manage labels and their workflow.
|
`cautious-journey` is a label manager and state machine for remote APIs. It creates and updates labels to match
|
||||||
|
the configuration, can replace labels to create complex workflows, and supports multiple projects with shared or
|
||||||
|
unique labels.
|
||||||
|
|
||||||
## Label
|
## Labels
|
||||||
|
|
||||||
While `cautious-journey` reads issue data, labels are what it cares about.
|
Labels come in two varieties: individual flags and mutually-exclusive states. These are equivalent to
|
||||||
|
checkboxes and radio groups in web forms, with the state changes between values forming a state machine within
|
||||||
|
each group of state labels.
|
||||||
|
|
||||||
### Flag Label
|
### Flag Labels
|
||||||
|
|
||||||
Flag labels are set individually. While they may depend on or even remove each other,
|
Flag labels are set individually. They support basic change sets, like `adds` and `removes`. While flags are
|
||||||
they are not connected directly.
|
independent by default, they can depend on other labels in `requires`.
|
||||||
|
|
||||||
### State Label
|
#### Change Sets
|
||||||
|
|
||||||
State labels are set from a group. Only one value from each state may be set at a time,
|
If the flag in question is present on an issue, then:
|
||||||
and the highest priority value automatically replaces any others.
|
|
||||||
|
|
||||||
#### State Value
|
- the labels listed in `adds` will be added
|
||||||
|
- the labels listed in `removes` will be removed
|
||||||
|
|
||||||
Individual values within the state.
|
### State Labels
|
||||||
|
|
||||||
|
State labels are set from a group of values. Only one value from each state may be present at a time; if more than
|
||||||
|
one value exists, the highest priority will be kept. Each value can define a set of potential state changes, which
|
||||||
|
will replace the current value with another label (flag or state value).
|
||||||
|
|
||||||
|
#### State Values
|
||||||
|
|
||||||
|
State values are mutually exclusive, but are normal labels in other ways. They support basic change sets, like
|
||||||
|
`adds` and `removes`, along with a set of potential changes in `becomes`.
|
||||||
|
|
||||||
#### State Changes
|
#### State Changes
|
||||||
|
|
||||||
|
@ -75,19 +89,30 @@ labels will be promoted to `status/in-progress`, and both the `status/new` and `
|
||||||
|
|
||||||
## Remote
|
## Remote
|
||||||
|
|
||||||
`cautious-journey` manipulates issues and labels that exist on some remote service.
|
`cautious-journey` typically connects to some remote service to manage labels there. You can choose which remote
|
||||||
|
should be used for each project.
|
||||||
|
|
||||||
### Github Remote
|
### Github Remote
|
||||||
|
|
||||||
Connects to a Github repository.
|
Connects to a Github repository.
|
||||||
|
|
||||||
- `path`
|
- `type: github-remote`
|
||||||
|
- `data:`
|
||||||
|
- `type: app`
|
||||||
|
- `appId`
|
||||||
|
- `installationId`
|
||||||
|
- `privateKey`
|
||||||
|
- `type: token`
|
||||||
|
- `token`: personal token with `repo` scope
|
||||||
|
|
||||||
### Gitlab Remote
|
### Gitlab Remote
|
||||||
|
|
||||||
Connects to a Gitlab repository.
|
Connects to a Gitlab repository.
|
||||||
|
|
||||||
- `path`
|
- `type: gitlab-remote`
|
||||||
|
- `data:`
|
||||||
|
- `type: token`
|
||||||
|
- `token`: personal access token with `api` scope
|
||||||
|
|
||||||
## Sync
|
## Sync
|
||||||
|
|
||||||
|
@ -95,8 +120,11 @@ Update issue labels or the labels themselves.
|
||||||
|
|
||||||
### Sync Issues
|
### Sync Issues
|
||||||
|
|
||||||
Update issue labels.
|
Update issue labels by resolving state changes and other change sets.
|
||||||
|
|
||||||
### Sync Labels
|
### Sync Projects
|
||||||
|
|
||||||
Update project labels.
|
Update project labels to match the `flags` and `states` provided in the config.
|
||||||
|
|
||||||
|
The project config is considered the source of truth when syncing projects, and the remote labels will be
|
||||||
|
updated to match the config.
|
||||||
|
|
Loading…
Reference in New Issue