cautious-journey/docs/arch.md

Architecture Guide

This guide describes the program architecture.

Contents

• Architecture Guide
  • Contents
  • Summary
  • Labels
    • Flag Labels
      • Change Sets
    • State Labels
      • State Values
      • State Changes
  • Remote
    • Github Remote
    • Gitlab Remote
  • Sync
    • Sync Issues
    • Sync Projects

Summary

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.

Labels

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 Labels

Flag labels are set individually. They support basic change sets, like adds and removes. While flags are independent by default, they can depend on other labels in requires.

Change Sets

If the flag in question is present on an issue, then:

• the labels listed in adds will be added
• the labels listed in removes will be removed

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 labels may replace one value with another using normal change rules, with the addition of a list of matching labels that must be present for the state change to be resolved.

For example, a state with three values like so:

projects:
  - name: foo
    flags:
      - name: next
    states:
      - name: status
        values:
          - name: new
            becomes:
              - adds: [status/in-progress]
                matches: [next]
          - name: in-progress
            becomes:
              - adds: [status/done]
                matches: [next]
          - name: done
            becomes:
              - adds: [status/new]
                matches: [next]

Each time cautious-journey evaluates the labels on this project, any issues with the status/new and next labels will be promoted to status/in-progress, and both the status/new and next labels will be removed.

Remote

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

Connects to a Github repository.

• type: github-remote
• data:
  • type: app
    • appId
    • installationId
    • privateKey
  • type: token
    • token: personal token with repo scope

Gitlab Remote

Connects to a Gitlab repository.

• type: gitlab-remote
• data:
  • type: token
    • token: personal access token with api scope

Sync

Update issue labels or the labels themselves.

Sync Issues

Update issue labels by resolving state changes and other change sets.

Sync Projects

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.