Merge pull request #94 from terrastruct/v0.4.2

v0.4.2

README.md

@@ -1,16 +1,28 @@
-# TALA
+<div align="center">
+  <img width="205" alt="TALA logo" src="https://user-images.githubusercontent.com/3120367/211999109-3b1ef11c-8efa-4473-aa8c-5ef43d7dc962.png">
+  <h1>
+    TALA
+  </h1>
+ </div>
+
 
 TALA is a diagram layout engine designed specifically for software architecture diagrams,
-though it works well in other domains too. TALA is closed-source (for now). This
-repository is primarily for installation instructions. You can also use this repository to
-report issues, ask questions, and request features.
+though it works well in other domains too.
+
+TALA is closed-source. This repository is primarily for installation instructions. You can
+also use this repository to report issues, ask questions, and request features.
 
 To learn more about TALA, please visit
-[https://terrastruct.com/tala](https://terrastruct.com/tala).
+[https://terrastruct.com/tala](https://terrastruct.com/tala). Note that this is a paid
+layout engine, which requires a license for any commercial use. The license is purchasable
+in that same link. TALA is free to evaluate, but without a license, will render with a
+watermark.
 
 To compare TALA with other layout engines, please visit
 [https://text-to-diagram.com](https://text-to-diagram.com/?a=d2&layout_a=tala&b=d2&layout_b=dagre&example=chess).
 
+[User Manual (PDF)](https://github.com/terrastruct/TALA/raw/master/TALA_User_Manual.pdf)
+
 ## Rendering samples
 
 You can see the `.d2` text for these in [./docs/d2](./docs/d2). Samples are
@@ -22,16 +34,30 @@ You can see the `.d2` text for these in [./docs/d2](./docs/d2). Samples are
 
 ## Installation
 
+### Install script
+
+The most convenient way to install is through the install script.
+
 ```sh
-curl -fsSL https://d2lang.com/install.sh | sh -s -- --tala --dryrun
+# With --dry-run the install script will print the commands it will use
+# to install without actually installing so you know what it's going to do.
+curl -fsSL https://d2lang.com/install.sh | sh -s -- --tala --dry-run
 # If things look good, install for real.
 curl -fsSL https://d2lang.com/install.sh | sh -s -- --tala
 ```
 
-You can also find binaries
-[Releases](https://github.com/terarstruct/TALA/releases) page for Linux and MacOS, for
-both AMD and ARM. Download the appropriate one for your OS to a directory
-in your path. Windows coming soon.
+You can also find binaries [Releases](https://github.com/terrastruct/TALA/releases) page
+for Linux, MacOS and Windows, for both AMD and ARM. Download the appropriate one for your
+OS to a directory in your path.
+
+### macOS (Homebrew)
+
+If you're on macOS, you can alternatively install with `brew`. (the install script above
+does this automatically if you have `brew` installed).
+
+```sh
+brew install terrastruct/tap/tala
+```
 
 ### Post-install
 
@@ -52,16 +78,54 @@ setting the environment variable `D2_LAYOUT`.
 D2_LAYOUT=tala d2 in.d2 out.svg
 ```
 
+### Seeds
+
+Optimal placements of nodes that minimizes distance and crossings is an NP-hard problem.
+TALA searches with heuristics to get an approximation. This search space has some
+randomness at each step. Choosing a different seed for this randomness can have signficant
+impact on the overall layout, as it may converge on an entirely different one.
+
+For advanced usage of TALA, you may specify the seed to get a different layout:
+
+```d2
+d2 --layout tala --tala-seeds 44 input.d2
+```
+
 ### Add API token (optional)
 
 You may skip this step if you are just evaluating.
 
+#### As environment variable
+
 If you have an API token, copy and paste it into your environment variables. E.g.
 
 ```bash
 export TSTRUCT_TOKEN = "tstruct_..."
 ```
 
+#### As config file
+
+You can also use a JSON file as config. The benefit to this is that when the TALA license
+expires and has to renew, it will swap out the key for you automatically in the background
+with the updated one.
+
+By default, TALA finds the configuration file at the following path:
+
+`$HOME/.config/tstruct/auth.json`:
+
+```json
+{
+  "api_token": "tstruct_xxx"
+}
+```
+
+You can change where this path is by configuring it with the following environment
+variable:
+
+```bash
+export TSTRUCT_AUTHFILE = /var/local/...
+```
+
 ## License keys
 
 TALA is freely installable and locally runnable for evaluation. You'll need an API token

ci/release/changelogs/v0.2.10.md

@@ -0,0 +1,9 @@
+#### Features 🚀
+
+#### Improvements 🧹
+
+- New algorithm for hierarchy crossing minimization
+
+#### Bugfixes ⛑️
+
+- Fixes compatability bug with D2 v0.1.3

ci/release/changelogs/v0.2.11.md

@@ -0,0 +1,11 @@
+#### Features 🚀
+
+- TALA's core algorithm seed can be specified.
+
+#### Improvements 🧹
+
+- Reduces edge crossings such that no port swaps can result in less crossings.
+
+#### Bugfixes ⛑️
+
+- Fixes an alignment issue with descendants. [#15](https://github.com/terrastruct/TALA/issues/15)

ci/release/changelogs/v0.2.12.md

@@ -0,0 +1,3 @@
+#### Improvements 🧹
+
+- Up to 2x faster runtime

ci/release/changelogs/v0.2.13.md

@@ -0,0 +1,3 @@
+#### Bugfixes ⛑️
+
+- Fixes edge case where children of container could escape their containers.

ci/release/changelogs/v0.2.14.md

@@ -0,0 +1,14 @@
+#### Improvements 🧹
+
+- Improves cluster arrangements and edge routing
+- Positions shapes closer to neighbors outside its own container
+- Reduce edge routing runtime by ~10%
+- Improves hierarchy algorithm to place objects at different levels when appropriate
+
+#### Bugfixes ⛑️
+
+- Fixes a rare `panic` while reducing gap between nodes
+- Fixes a rare `panic` with sequences (connected `step` shapes)
+- Fixes a rare panic with clusters
+- Fixes a rare panic when children of a container are connected to different childrens of different containers
+- Fixes an error where a connection route sometimes couldn't be found from a center step of a sequence

ci/release/changelogs/v0.2.15.md

@@ -0,0 +1,11 @@
+#### Improvements 🧹
+
+- Padding reduced on containers to align with more compact look and feel of D2 0.2.
+- `sql_table` routing switched from using hierarchical layout engine to orthogonal.
+- Diagrams with multiple subgraphs are more compact.
+- Much improved hierarchical alignments for diagrams where connections skip hierarchy levels (e.g. a node in the first row connected to another 2 rows down).
+
+#### Bugfixes ⛑️
+
+- Fixes an issue with hierarchy leveling where connections between two nodes of the same level could occur.
+- `sql_table` connections where column is not specified no longer always points to first column.

ci/release/changelogs/v0.2.5.md

@@ -0,0 +1,2 @@
+v0.2.5 fixes a bug in the make install script to create the necessary directories under
+prefix automatically instead of erroring out.

ci/release/changelogs/v0.2.6.md

@@ -0,0 +1,5 @@
+#### Improvements 🧹
+
+- Route between table columns, instead of just tables, to show the exact relationship in Entity Relationship (ER) diagrams
+- Improved consistency in the automatic direction of layouts
+- `make install` defaults to installation to `/usr/local` as before but now if `/usr/local` is not accessible to the current user, it will use `~/.local` instead of prompting for sudo. You can pass `--prefix /usr/local` to force installation into `/usr/local` with a prompt for sudo.

ci/release/changelogs/v0.2.7.md

@@ -0,0 +1,3 @@
+#### Improvements 🧹
+
+- The Windows release binary is now suffixed correctly with `.exe` [#388](https://github.com/terrastruct/d2/issues/388)

ci/release/changelogs/v0.2.8.md

@@ -0,0 +1,7 @@
+#### Features 🚀
+
+- keyword `direction` is now supported in containers to adjust layouts towards the specified direction
+
+#### Improvements 🧹
+
+- edge routing is now up to 2x faster

ci/release/changelogs/v0.2.9.md

@@ -0,0 +1,11 @@
+#### Features 🚀
+
+- Loops (self edges) are now supported
+
+#### Improvements 🧹
+
+- Node alignment are better
+
+#### Bugfixes ⛑️
+
+- Fixes a rare panic that could happen when a `near` relation was defined between clustered nodes

ci/release/changelogs/v0.3.0.md

@@ -0,0 +1,55 @@
+TALA 0.3.0 implements position-locking to give control over parts of the diagram where you need it. This is an advanced feature that opens up a world of possibilities to create small bubbles of customized layouts and combine it with autolayout. For example, here's a legend:
+
+<img src="https://raw.githubusercontent.com/terrastruct/TALA/master/docs/assets/legend.png" />
+
+```d2
+Legend: {
+  top: 0
+  left: 0
+  blue: "" {
+    width: 20
+    height: 20
+    left: 0
+    top: 0
+    style.stroke: black
+  }
+  blue-explanation: Actions {
+    shape: text
+    left: 50
+    top: 0
+  }
+
+  green: "" {
+    width: 20
+    height: 20
+    left: 0
+    top: 50
+    style.fill: honeydew
+    style.stroke: black
+  }
+  green-explanation: Intermediate artifacts {
+    shape: text
+    left: 50
+    top: 50
+  }
+}
+```
+
+We're excited to see all the creative diagrams this enables!
+
+#### Features 🚀
+
+- `top` and `left` positions implemented.
+
+#### Improvements 🧹
+
+- ~30% faster for large, connected diagrams
+- Much faster gap normalization for all diagrams
+- Bin-packing algorithm improved to reduce whitespace between non-connected subgraphs
+
+#### Bugfixes ⛑️
+
+- Fixes label placements avoiding connections that weren't actually obstructing
+- Fixes a rare panic that could with cluster nodes
+- Edges could sometimes route through nodes that were not part of its subgraph
+- Edges between containers that were perfectly aligned was sometimes unable to find a route.

ci/release/changelogs/v0.3.1.md

@@ -0,0 +1 @@
+hotfix to last release where the plugin would give an error saying container self-edges were not allowed when they are.

ci/release/changelogs/v0.3.10.md

@@ -0,0 +1,11 @@
+#### Features 🚀
+
+- Configure timeout value with D2_TIMEOUT env var.
+
+#### Improvements 🧹
+
+#### Bugfixes ⛑️
+
+- Fixes grid label font size
+- Prevents scenarios where bidirectional edges with different arrowheads could overlap each other
+- Fixes a rare bug where shapes in a tree layout could sometimes be misplaced

ci/release/changelogs/v0.3.11.md

@@ -0,0 +1,10 @@
+#### Improvements 🧹
+
+- Connections from a `sql_table` column and a non-column will now route to the specific column
+- Reduce scenarios where nodes could end up far from a connected node with a fixed position
+- Reduce rare scenarios where a subgraph within a container could end up far from other subgraphs connected to shapes outside the container
+
+#### Bugfixes ⛑️
+
+- Fixes a rare bug resulting in non-deterministic layouts
+- Fixes scenarios where trees could become very wide with excessive spacing between subtrees

ci/release/changelogs/v0.3.2.md

@@ -0,0 +1,19 @@
+Label positions improve significantly!
+
+### Before
+
+<img width="1003" alt="Screen Shot 2023-03-04 at 11 05 20 AM" src="https://user-images.githubusercontent.com/3120367/222924247-51d0b491-71b5-4d3d-89fd-e22af6e991f4.png">
+
+### After
+
+<img width="1036" alt="Screen Shot 2023-03-04 at 11 05 26 AM" src="https://user-images.githubusercontent.com/3120367/222924254-3b0906e0-360d-44e5-b299-62a8850cab18.png">
+
+#### Improvements 🧹
+
+- Improves edge label positioning
+- Improves node label positioning
+
+#### Bugfixes ⛑️
+
+- Fixes a rare bug that could affect edge routes
+- Fixes a bug with top and left keywords in nested containers that could cause layout errors

ci/release/changelogs/v0.3.3.md

@@ -0,0 +1,8 @@
+#### Improvements 🧹
+
+- Clusters are sized such that labels always have enough room.
+- Improves shape-specific label position preferences (for example, parallelograms now prefer placing labels within the shape).
+
+#### Bugfixes ⛑️
+
+- Nested node labels no longer overlap container boundaries occasionally

ci/release/changelogs/v0.3.4.md

@@ -0,0 +1,34 @@
+This release brings massive improvements in performance. Screenshot from our internal benchmarks on a batch of tests, comparing this release vs the last:
+
+<img width="540" alt="Screen Shot 2023-03-18 at 4 03 09 PM" src="https://user-images.githubusercontent.com/3120367/226144882-c6746a65-1f60-4a55-8382-9e5ea2a686a2.png">
+
+As a result of this, TALA by default now executes 3 runs in parallel with different seeds, and picking the best one for you. This should produce better results at a much higher rate!
+
+
+#### Features 🚀
+
+- You can now pass in multiple seeds, and TALA will race multiple layout runs with
+  different seeds, choosing the best outcome. See the TALA Manual for more.
+
+#### Improvements 🧹
+
+- Improves subgraph compaction giving space for better edges
+- Improved edge routing for clustered nodes
+- Significantly speeds up edge routing with many edges
+- Significant performance improvements
+- Uses up to 56% less memory for layouts with `sql_table`s
+
+#### Bugfixes ⛑️
+
+- Fixes a rare condition that allowed nodes with self loops to escape their containers
+- Fixes edge from container going through descendants
+- Fixes a bug that could cause some asymmetrical edge routing
+- Fixes container shapes sometimes not having enough padding to fit icons
+- Fixes the alignment of nodes connected to sequence steps
+- Fixes the placement of clustered nodes connected to sequences
+
+#### Breaking Changes
+
+- `tala-seed` changed to `tala-seeds`. You can still continue to pass in a single number,
+  same as before. But the name change is reflective that it can now take in multiple
+  seeds.

ci/release/changelogs/v0.3.5.md

@@ -0,0 +1,18 @@
+Way, way faster!
+
+#### Improvements 🧹
+
+- Edge routing is up to 31% faster
+- Improves layout of clusters
+- Node placement is up to 2x faster
+- Up to 41% less memory usage
+- Avoids clustering nodes when their sizes are disproportionately different
+- Prevent image labels from being placed over the image in some cases
+
+#### Bugfixes ⛑️
+
+- Fixes a rare bug where container children place outside of container
+- Fixes self-loop sizing on containers
+- Fixes node drift in certain cases
+- Fixes an issue where unlabeled connections could completely overlap each other
+- Fixes a bug with node alignments

ci/release/changelogs/v0.3.6.md

@@ -0,0 +1,5 @@
+Compatible with D2 0.4.1 onwards.
+
+#### Improvements 🧹
+
+- Improves edge routing between hierarchies and non-hierarchies

ci/release/changelogs/v0.3.7.md

@@ -0,0 +1,14 @@
+#### Features 🚀
+
+- Nodes are expanded to aesthetically fit all connections if not enough room with default dimensions
+- Arrowhead labels are considered in autolayout and avoid overlaps as much as possible
+
+#### Improvements 🧹
+
+- Pairs of nodes prefer horizontal arrangements given multiple connections with labels
+
+#### Bugfixes ⛑️
+
+- Fixes a rare bug using `near` to a node in a tree structure
+- Fixes a rare bug positioning nested node clusters
+- Fixes a rare panic involving edge labels

ci/release/changelogs/v0.3.8.md

@@ -0,0 +1,19 @@
+#### Features 🚀
+
+- Containers respect `width` and `height` settings, though they will expand to fit content if needed
+
+#### Improvements 🧹
+
+- Node placement is up to 2x faster
+- Avoids overlapping edges when they have different arrowheads
+- `direction` keyword now affects bidirectional edges
+- Spacing between nodes ensures that labels will fit
+- Edges stick to outer bounds of shapes with `3d` or `multiple`
+- Improves layouts for clusters with both icons and labels
+- Improves edge balancing to look more symmetrical
+
+#### Bugfixes ⛑️
+
+- Fixes shape and connection labels potentially overlapping arrowhead labels
+- Fixes a bug with arrowhead labels on the `-` end of a connection
+- Fixes container shapes sometimes swapping positions with another shape errantly

ci/release/changelogs/v0.3.9.md

@@ -0,0 +1,7 @@
+#### Improvements 🧹
+
+- layout is up to 3x faster and uses as little as 1/3 the memory after many optimizations
+
+#### Bugfixes ⛑️
+
+- Compatability with D2 0.5

ci/release/changelogs/v0.4.0.md

@@ -0,0 +1,31 @@
+TALA 0.4.0 is a massive improvement in layout positions of a wide range of diagrams.
+
+<img width="814" alt="Screenshot 2024-07-08 at 2 44 49 PM" src="https://github.com/terrastruct/TALA/assets/3120367/a4d3ca21-a0bc-4771-9c82-ab2fc736a439" />
+
+#### Improvements 🧹
+
+- Unconnected nodes and subgraphs are packed more tightly together
+- Containers of similar sizes with indirect connections are aligned better
+- Some diagrams escape local minimas better
+- Nodes connected on both sides are more equidistant to both
+- Cluster edge labels prioritize not intersecting with other cluster edges
+- Node labels reposition to avoid overlapping with icons
+- Node icons reposition to avoid overlapping with fixed labels
+- Multiple edges between nodes are now ordered (left-right and top-down) by the order they were declared
+- Edge routes between grid cells avoid node labels
+- Edge routes consider paths that go through "invisible" nodes and edges (e.g. zero opacity)
+- When only one of `width` or `height` is specified for a container, nodes will full up better to reduce unused space
+- Tree structures are built more symmetrically
+- Containers with edges going into its children are pulled closer together to the other edge endpoint
+- Clusters of nodes are oriented more reasonably to facilitate better routes
+- Clusters routes more often converge on a single point in the middle to form the "fork" aesthetic
+- Node labels are positioned in areas of more space
+- Edge labels avoid fixed node icon positions
+
+#### Bugfixes ⛑️
+
+- Fixes extra warnings that appeared with an invalid token
+- Fixes panic when edges were defined between actors in different sequence diagrams
+- Fixes custom label positions and icon positions not working for nodes in tree structures
+- Disallow edges with different styles (e.g. stroke colors) from sharing routes
+- Some direct straight routes weren't being considered between two non-diagonal nodes

ci/release/changelogs/v0.4.2.md

@@ -0,0 +1,19 @@
+#### Features 🚀
+
+- `tala-seeds` can be specified in the source code through `vars` (see manual for more)
+
+#### Improvements 🧹
+
+- Containers expand to fit large labels
+- Edge labels are placed more intelligently to avoid overlaps
+- Nodes with multiple edges to another node with long edge labels are positioned more intelligently
+- Two nodes with > 2 edges with labels strongly prefer being in horizontal orientation to each other. This increases the chance of their multiple edge labels being readable.
+- Hierarchies with multiple parents are more centered
+- Up to 20% faster
+
+#### Bugfixes ⛑️
+
+- Fixed rare panic when hierarchies with containers were used
+- Various edge cases that affect layout have been fixed
+- Fixes rare panic with multiple edges with arrowhead labels on the same table column
+- Fixes rare panic using step shapes connected to other shapes