diff --git a/docs/dev.md b/docs/dev.md index 4ef72be..574c92f 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -8,9 +8,10 @@ - [Linux](#linux) - [Mac OS](#mac-os) - [Checking Out the Project](#checking-out-the-project) - - [Building](#building) + - [Build](#build) - [Compiling Typescript](#compiling-typescript) - [Running Mocha Tests](#running-mocha-tests) + - [Running Bundled Code](#running-bundled-code) ## Setup @@ -66,7 +67,7 @@ Clone the repository: You can also clone the repository through Github Desktop: -* [x-github-client://openRepo/https://github.com/ssube/cautious-journey](x-github-client://openRepo/https://github.com/ssube/cautious-journey) +- [x-github-client://openRepo/https://github.com/ssube/cautious-journey](x-github-client://openRepo/https://github.com/ssube/cautious-journey) Change the directory: @@ -74,7 +75,7 @@ Change the directory: > cd ~/Documents/GitHub/cautious-journey/ ``` -## Building +## Build Building the app is done through `make` and its targets. To see a list of available targets: @@ -104,3 +105,13 @@ This will compile the code and run tests. ### Running Mocha Tests Tests use Mocha: https://mochajs.org/#getting-started + +```shell +> make test +``` + +### Running Bundled Code + +```shell +> node ./out/index.js --help +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index cd875ba..7dfa03b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -17,47 +17,106 @@ This guide explains how to start using `cautious-journey` to manage project and - [Configuring Multiple Projects](#configuring-multiple-projects) - [Running Select Projects](#running-select-projects) - [Remotes](#remotes) + - [Available Remotes](#available-remotes) - [Copying Project Remotes](#copying-project-remotes) - [Commands](#commands) - - [Sync Labels](#sync-labels) - - [Sync Issues](#sync-issues) + - [Sync Issue Labels](#sync-issue-labels) + - [Sync Project Labels](#sync-project-labels) - [Changes](#changes) - [Flag Changes](#flag-changes) - [State Changes](#state-changes) + - [State Value Changes](#state-value-changes) + - [Examples](#examples) + - [Example: Conflicting Labels](#example-conflicting-labels) + - [Example: Release Workflow](#example-release-workflow) ## Setup ### Installing -TODO: how would you install the app? +To use the latest version of `master` from Docker Hub: + +```shell +> docker pull ssube/cautious-journey:master +``` + +To use the latest release from npm: + +```shell +> yarn add -g cautious-journey +``` + +To use the latest code from Github, following the [developer guide's `setup` and `build` steps](./dev.md). ### Running -TODO: how would you run the app? +To run the Docker image: + +```shell +> docker run --rm -it ssube/cautious-journey:master --help +``` + +TODO: mounting config file into container + +To run the npm package: + +```shell +> $(yarn global bin)/cautious-journey --help +``` + +To run the latest code, once it has been built: + +```shell +> node --require esm ./out/index.js --help +``` + +To pretty-print logs for any of the above methods, pipe the output through `bunyan`: + +```shell +> 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 -TODO: how would you configure the app? +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 -TODO: what are labels? what kinds of labels do we support? +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 -TODO: what are flag labels? +Flags exist independently, but have the same rules as other labels: + +- `adds` +- `removes` +- `requires` ### State Labels -TODO: what are 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 -TODO: what are projects? how are they managed? how do you pick which projects to run? +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 -TODO: how would you configure the app to run for 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 @@ -65,7 +124,18 @@ TODO: how would you run a single project, or a subset? ## Remotes -TODO: what are remotes? how are they configured? +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 @@ -73,22 +143,62 @@ TODO: how would you share a remote config block between two projects? ## Commands -TODO: what commands are present? +The program can run in a few different modes: -### Sync Labels +- sync issue labels +- sync project labels -TODO: what happens when you sync the project labels? +### Sync Issue Labels -### Sync Issues +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. -TODO: what happens when you sync the issue labels? +### 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 -TODO: how are flag labels added and removed? +- `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 -TODO: how are state labels added and removed? +States have the base rules: + +- `adds`: labels to be added +- `removes`: 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 added + - `matches`: + - 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