5.4 KiB
Getting Started
This guide explains how to start using cautious-journey
to manage project and issue labels.
Contents
Setup
Installing
To use the latest version of master
from Docker Hub:
> docker pull ssube/cautious-journey:master
To use the latest release from npm:
> yarn add -g cautious-journey
To use the latest code from Github, following the developer guide's setup
and build
steps.
Running
To run the Docker image:
> docker run --rm -it ssube/cautious-journey:master --help
TODO: mounting config file into container
To run the npm package:
> $(yarn global bin)/cautious-journey --help
To run the latest code, once it has been built:
> node --require esm ./out/index.js --help
To pretty-print logs for any of the above methods, pipe the output through bunyan
:
> docker run --rm -it ssube/cautious-journey:master --help | $(yarn global bin)/bunyan
> $(yarn global bin)/cautious-journey --help | $(yarn global bin)/bunyan
> node --require esm ./out/index.js --help | ./node_modules/.bin/bunyan
Configuring
Configuration is provided as a YAML file, typically named ~/.cautious-journey.yml
.
Mac OS users may want to omit the leading dot from the filename and use ~/cautious-journey.yml
instead, to make
the file visible in Finder. The hidden filename will be used in examples.
Labels
Labels are the unit of data being manipulated by cautious-journey. Labels may exist independently (flags) or as part of a group (state values), with rules to add, remove, and replace labels.
Flag Labels
Flags exist independently, but have the same rules as other labels:
adds
removes
requires
State Labels
State labels exist in groups, of which only one value can be set at a time. If multiple values are set, the highest priority value will be kept, unless some rule removes it.
Projects
Projects usually map to a repository on some remote service, like Github or Gitlab. Each project can have its own set of labels and random colors.
Configuring Multiple Projects
The config file has a projects
key at its root, containing a list of projects to be processed.
colors
flags
name
remote
states
Running Select Projects
TODO: how would you run a single project, or a subset?
Remotes
Remotes abstract the API calls, requests, and writes needed to persist data in some service or file.
Available Remotes
The following remote services are supported:
- Github
Support for more is planned:
- File
- Gitlab
Copying Project Remotes
TODO: how would you share a remote config block between two projects?
Commands
The program can run in a few different modes:
- sync issue labels
- sync project labels
Sync Issue Labels
This mode will look through each issue on the project, open or closed, and check for label updates. Labels will be resolved using the project's rules, and a comment left recording any changes.
Sync Project Labels
This mode will look through the project labels, ensuring they are up to date with the project labels in the config. Missing labels will be created, extra labels will be deleted, and existing labels will be updated to match the config.
Changes
Every change can add or remove flags, but certain labels may have their own rules.
Flag Changes
adds
: labels to be added,{ name: string }
removes
: labels to be removed,{ name: string }
requires
:- all required labels must be present
- if any required labels are missing, this flag will be removed
adds
/removes
rules will not be run if this flag is removed
State Changes
States have the base rules:
adds
: labels to be addedremoves
: labels to be removed
State Value Changes
State values have the base rules, which will be combined with their parent state's adds
/removes
, as well as
a list of potential state changes that may replace the value, if matching labels exist.
becomes
adds
: labels to be addedmatches
:- all matched labels must be present
- if any matched labels are missing, this change will be skipped
adds
/removes
rules will not be run if this change is skipped- if this change is run, this value will be removed
removes
: labels to be removed
Examples
Example: Conflicting Labels
TODO: describe a workflow with blocked
as a flag that removes any status
Example: Release Workflow
TODO: describe a workflow with status
state and next
/release
flags