fc4-framework

fc4-tool

A tool for reorganizing, restructuring, reformatting, and rendering FC4 diagrams.

CircleCI codecov

Purpose

As explained in The Toolset section of the FC4 Methodology:

This tool was created because when one uses Structurizr Express (SE) to position the elements of a diagram, SE regenerates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change. This makes the source harder to work with in a text editor and impossible to usefully diff from revision to revision — and without useful diffing it’s very difficult to do effective peer review.

So fc4-tool processes the YAML: cleans it up, applies a stable sort to all properties, removes empty properties, etc — so as to ensure that the changes applied in each revision are very small and specific and all extraneous changes are filtered out. This will hopefully enable effective peer review of revisions to the diagrams.

fc4-tool also:

Setup

Requirements

  1. A Java Runtime Environment (JRE) or Java Development Kit (JDK)
    1. On MacOS if you have Homebrew you can run brew cask install adoptopenjdk
  2. An installation of Chrome or Chromium 70–72 (inclusive)
    1. On MacOS:
      1. If you have Homebrew you can run brew cask install chromium
      2. Chromium/Chrome must be at either /Applications/Chromium.app or /Applications/Google Chrome.app

MacOS quick-start for Homebrew users: brew cask install adoptopenjdk chromium

Download and Install

  1. Download the archive for your platform from the latest release on the releases page
  2. Expand the archive
  3. Optional: move the extracted files to somewhere on your $PATH
    1. e.g. mv ~/Downloads/fc4/fc4* ~/bin/

Authoring Diagrams

Abridged Workflow

  1. Run in your terminal: fc4 edit path/to/diagram.yaml/or/dir
  2. Open a YAML file in your text editor and edit it
    1. Either a YAML file specified directly or one in or under a specified directory
  3. Whenever you save the file, fc4-tool will see the change, clean up the file (overwriting it) and render the diagram to a PNG file (overwriting that file, if it already existed)
  4. When you’d like to wrap up your session:
    1. Save the file one last time and wait for fc4-tool to process and render it
    2. Hit ctrl-c to exit fc4-tool
    3. Run git status and you should see that the YAML file has been created/changed and its corresponding PNG file has also been created/changed
    4. Commit both files

Full Workflow

Please see The Authoring Workflow section of the FC4 Methodology.

Requirements and Prerequisites for Development and Testing

Required

Running the Tests

  1. Use CI
  2. No, seriously, use CI!
  3. Just kidding, I know sometimes you need to run the tests locally ;)

With Docker

Run this in your shell:

bin/docker-test-run bin/tests

Without Docker

If you’re old-school and prefer to run tests on bare metal:

  1. Ensure that Clojure, Node, and Chromium/Chrome are installed
    1. On Macos with Homebrew: brew cask install adoptopenjdk chromium && brew install clojure npm
  2. Run:
    1. bin/download-all-deps
    2. bin/tests

Starting a REPL for Dev/Test

You could just run clj but you’re likely to want the test deps and dev utils to be accessible. So you’ll probably want to run clj -A:dev:test

Running the tests in a REPL

$ clj -A:dev:test
Clojure 1.9.0
=> (do
     (require '[eftest.runner :refer [find-tests run-tests]])
     (run-tests (find-tests "test") {:fail-fast? true})
     (print (char 7))) ; beep to get your attention
...

Running the Linter

For linting, this project uses cljfmt, via cljfmt-runner.

Contributors

Thank you all!

(If you notice that anyone is missing from this list, please open an issue or a PR — thank you!)