fix(docs): begin fleshing out getting-started guide

2020-08-16 17:35:33 -05:00 · 2020-08-16 17:35:33 -05:00 · cbf5c5195f
parent 06cb70d5a1
commit cbf5c5195f
2 changed files with 142 additions and 21 deletions
--- 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
+```
--- 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