1
0
Fork 0

fix(docs): describe state changes, values, and remote options

This commit is contained in:
ssube 2020-08-22 17:29:19 -05:00
parent 3935172126
commit 432ef13bb6
Signed by: ssube
GPG Key ID: 3EED7B957D362AF1
2 changed files with 53 additions and 25 deletions

View File

@ -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

View File

@ -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.