docs: add a working with components tutorial, fix diff bugs

This adds a new "Working with Components" tutorial as a follow up to Getting Started. It also fixes an issue where we would not see the appropriate information it the Diff sub-panel.
systeminit · Aug 21, 2024 · ec3a6b4 · ec3a6b4
1 parent 9508e32
commit ec3a6b4
Show file tree

Hide file tree

Showing 27 changed files with 240 additions and 27 deletions.
diff --git a/app/docs/src/.vitepress/config.ts b/app/docs/src/.vitepress/config.ts
@@ -70,6 +70,10 @@ export default defineConfig({
             text: "Getting Started",
             link: "/tutorials/getting-started",
           },
+          {
+            text: "Working with Components",
+            link: "/tutorials/working-with-components",
+          },
           {
             text: "Creating a new Asset",
             link: "/tutorials/creating-new-assets",

diff --git a/app/docs/src/reference/vocabulary.md b/app/docs/src/reference/vocabulary.md
@@ -6,6 +6,10 @@ This a reference to all of the vocabulary used in System Initiative.
 
 Anything that can be used on the canvas.
 
+## Component
+
+A component is the 'theoretical' half of a Model. It represents the configuration values you *want* something to have, while the Resource represents its real world values.
+
 ## Credential
 
 A credential is a type of component that stores secret data, and has
@@ -50,6 +54,8 @@ System Initiative. It is a graph that represents all of the code, components,
 resources, and functions that are in a workspace. We call it a "hypergraph"
 because it is multi-dimensional through the use of change sets.
 
+We know it's not an actual [hypergraph](https://en.wikipedia.org/wiki/Hypergraph). It's just less of a mouthful than 'multi-dimensional graph'.
+
 ## A Model
 
 When we refer to "a model", we mean a single Component/Resource pair.

diff --git a/app/docs/src/tutorials/getting-started.md b/app/docs/src/tutorials/getting-started.md
@@ -203,14 +203,3 @@ You learned how to:
 - Configure components by setting their properties
 - Connect components input and output sockets to dynamically configure them
 - Execute actions and create resources by applying a change set
-
-## Next Steps
-
-You can:
-
-- Follow the [Create Assets](./creating-new-assets.md) tutorial to learn about
-  how to program and extend System Initiative
-- Use your knowledge of AWS and System Initiative to learn how to create [AWS
-  VPCs]
-- Join us on [Discord](https://discord.com/invite/system-init) to ask any
-  questions you may have
diff --git a/app/docs/src/tutorials/index.md b/app/docs/src/tutorials/index.md
@@ -5,4 +5,5 @@ using System Initiative. They focus on helping you gain experience by doing,
 rather than explaining why things work the way they do.
 
 - [Getting Started](./getting-started.md) - learn the basics of building infrastructure and applications with System Initiative.
-- [Creating a new asset](./creating-new-assets.md) - learn how to extend System Initiative by creating your own new assets.
+- [Working with components](./working-with-components.md) - learn how to work more deeply with components in System Initiative.
+- [Creating a new asset](./creating-new-assets.md) - learn how to extend System Initiative by creating your own new assets.
diff --git a/app/docs/src/tutorials/working-with-components.md b/app/docs/src/tutorials/working-with-components.md
@@ -0,0 +1,180 @@
+# Working with Components
+
+This tutorial will teach you how to work more deeply with [components](/reference/vocabulary/) in System Initiative.
+
+To follow along, you should:
+
+1. Finish the [Getting Started tutorial](./getting-started), to have basic knowledge of System Initiative.
+
+2. You should have your System Initiative workspace open in another window.
+
+## Create a change set
+
+![Create a change set](./working-with-components/create-a-change-set.png)
+
+Click the create change set button.
+
+Name your new change set `Exploring Properties`, and click the `Create change set` button.
+
+## Add a Docker Image component and set its properties
+
+![Add a Docker Image component and set its properties](./working-with-components/add-a-docker-image-component-and-set-its-properties.png)
+
+Click on `Docker Image` from the `Docker` category of the asset pallete, and drop it inside your workspace.
+
+Name your Docker Image component `nginx`.
+
+## Observe the Docker Images Qualification
+
+![Observe the Docker Images Qualification](./working-with-components/observe-the-docker-images-qualification.png)
+
+Notice the red hexagon in the lower right of your `nginx` Docker Image component. This is the [qualification](/reference/vocabulary#qualification) icon - it is warning you that your Docker Image component is misconfigured.
+
+:::tip
+You can also see a components qualification status in the Diagram Outline, the Component panel, and the Qualifications sub-panel.
+:::
+
+## Investigate the Docker Images Failing Qualification
+
+![Investigate the Docker Image](./working-with-components/investigate-the-docker-images-failing-qualification.png)
+
+Click the red hexagon on you `nginx` Docker Image component. The properties panel will change to the `Qualifications` sub-panel.
+
+You will see that your Docker Image is failing the `Docker Image Exists` qualification, with the error message 'no image available'.
+
+## Fixing the failing Qualification
+
+![Fixing the Failing Qualification](./working-with-components/fixing-the-failing-qualification.png)
+
+Select the `Attributes` sub-panel.
+
+Set the `image` property to `nginx`.
+
+The qualification icon will then turn green, confirming that a Docker Image named `nginx` exists in the Docker Hub.
+
+## Add a Butane component and set its properties
+
+![Add a Butane component](./working-with-components/add-a-butane-component-and-set-its-properties.png)
+
+[Butane](https://coreos.github.io/butane/) is a configuration file format used by the [Fedora CoreOS](https://fedoraproject.org/coreos/) operating system.
+
+Click on `Butane` from the `CoreOS` category of the asset pallete, and drop it inside your workspace.
+
+Name your Butane component `Web Server Config`.
+
+## Observe the systemd/units property of the Butane component
+
+![Observe the systemd units](./working-with-components/observe-the-systemd-units-property-of-the-butane-component.png)
+
+The `systemd/units` property of the `Web Server Config` takes an array (as indicated by the `[ ]` symbol in front of it). It is currently empty, and configured to be automatically set via a socket.
+
+## Manually setting the systemd/units property
+
+![Manually setting the systemd units property](./working-with-components/manually-setting-the-systemd-units-property.png)
+
+To manually set a property that would otherwise be configured by a socket, click the `set` dropdown, and select `manually`.
+
+Click the `Add array item` button to add an entry titled `unit[0]` to the `systemd/units` array.
+
+Set the `name` property of `unit[0]` to `manual-unit`.
+
+:::tip
+Notice that the `Web Server Config` is now failing its qualification, as this is not a valid name for a Systemd unit file!
+:::
+
+## Deleting the system/units/unit[0] entry
+
+![Deleting the System/units/unit0 entry](./working-with-components/deleting-the-system-units-unit-0-entry.png)
+
+To delete the `unit[0]` entry, click the trash can icon in the header.
+
+## Connect the Docker Image component to the Butane component
+
+![Connect the Docker Image to Butane](./working-with-components/connect-the-docker-image-component-to-the-butane-component.png)
+
+Switch the systemd/units property to be set `via socket`.
+
+Connect the `Container Image` output socket of your `nginx` Docker Image component to the `Container Image` input socket of your `Web Server Config` Butane component.
+
+## Observe the new system/units/unit[0] entry
+
+![Observe the new system/units entry](./working-with-components/observe-the-new-system-units-unit-0-entry.png)
+
+The new `unit[0]` entry is now set via a function, as indicated by the `f(x)` icon.
+
+The `name`, `contents`, and `enabled` properties have their values inferred by the configuration of your `nginx` docker image.
+
+## Viewing large properties
+
+![Viewing large properties](./working-with-components/viewing-large-properties.png)
+
+Some properties, such as `contents`, are too long to display in the panel. You can hover over the field and then click the icon to have them pop-out to a modal for easy viewing.
+
+## Viewing generated code
+
+![Viewing generated code](./working-with-components/viewing-generated-code.png)
+
+Click the `Code` sub-panel to see the JSON code as it would be processed by Butane.
+
+## Apply the Change Set
+
+![Apply the Change Set](./working-with-components/apply-the-change-set.png)
+
+Press the Escape key, or click on the background of the canvas, to ensure the workspace itself is selected.
+
+Click the `Apply Change Set` button.
+
+Click the `Apply Changes` button in the modal to accept.
+
+## Create another Change Set
+
+![Create a new Change Set](./working-with-components/create-another-new-change-set.png)
+
+Click the `Create change set` button.
+
+Name your new change set `Exploring Part 2`, and click the `Create change set` button.
+
+## Add an exposed port to your Docker Image
+
+![Add an exposed port to your Docker Image](./working-with-components/add-an-exposed-port-to-your-docker-image.png)
+
+Click the `Add array item` button for the `ExposedPorts` property of your `nginx` Docker Image component.
+
+Set the `[0]` value to `80/tcp`.
+
+## Check the Diff for your Docker Image and Butane components
+
+![Check the Diff for your Docker Image and Butane Components](./working-with-components/check-the-diff-for-your-docker-image-and-butane-components.png)
+
+Click the `Diff` sub-panel for your `nginx` Docker Image component. You'll see the currently set properties for the component, and a visual diff of the changes made in this change set (compared to the values on HEAD).
+
+Click your `Web Server Config` Butane component, and you'll see that the entire systemd unit files contents have been updated.
+
+## View the Debugging information
+
+![View the Debugging information](./working-with-components/view-the-debugging-information.png)
+
+Click the `Debug` sub-panel for your `nginx` Docker Image component. Here you will find detailed debugging information about the selected components attributes, input sockets, and output sockets. This information is often useful when customizing or debugging System Initiative.
+
+## Clean Up
+
+![Clean up](./working-with-components/clean-up.png)
+
+Clean up your workspace by highlighting the `nginx` Docker image and the `Web Server Config` Butane components. Press the `Delete` key on your keyboard.
+
+Click the `Confirm` button in the dialog to acknowledge you want to delete these two components.
+
+Click the `Apply Change Set` button. Your `nginx` and `Web Server Config` components are now removed from your workspace.
+
+## Congratulations
+
+You've explored the properties panel! You learned how to:
+
+- Investigate failing qualifications
+- Change if properties are set automatically by sockets or manually
+- Adding items to arrays and maps
+- Delete items from arrays and maps
+- View large properties in a modal
+- See generated code for a component
+- View the diff between a component on a change set and head.
+- View detailed debugging information about your components
diff --git a/...rials/working-with-components/add-a-butane-component-and-set-its-properties.png b/...rials/working-with-components/add-a-butane-component-and-set-its-properties.png
diff --git a/...working-with-components/add-a-docker-image-component-and-set-its-properties.png b/...working-with-components/add-a-docker-image-component-and-set-its-properties.png
diff --git a/.../tutorials/working-with-components/add-an-exposed-port-to-your-docker-image.png b/.../tutorials/working-with-components/add-an-exposed-port-to-your-docker-image.png
diff --git a/app/docs/src/tutorials/working-with-components/apply-the-change-set.png b/app/docs/src/tutorials/working-with-components/apply-the-change-set.png
diff --git a/...-with-components/check-the-diff-for-your-docker-image-and-butane-components.png b/...-with-components/check-the-diff-for-your-docker-image-and-butane-components.png
diff --git a/app/docs/src/tutorials/working-with-components/clean-up.png b/app/docs/src/tutorials/working-with-components/clean-up.png
diff --git a/...-with-components/connect-the-docker-image-component-to-the-butane-component.png b/...-with-components/connect-the-docker-image-component-to-the-butane-component.png
diff --git a/app/docs/src/tutorials/working-with-components/create-a-change-set.png b/app/docs/src/tutorials/working-with-components/create-a-change-set.png
diff --git a/app/docs/src/tutorials/working-with-components/create-another-new-change-set.png b/app/docs/src/tutorials/working-with-components/create-another-new-change-set.png
diff --git a/...rc/tutorials/working-with-components/deleting-the-system-units-unit-0-entry.png b/...rc/tutorials/working-with-components/deleting-the-system-units-unit-0-entry.png
diff --git a/...docs/src/tutorials/working-with-components/fixing-the-failing-qualification.png b/...docs/src/tutorials/working-with-components/fixing-the-failing-qualification.png
diff --git a/...working-with-components/investigate-the-docker-images-failing-qualification.png b/...working-with-components/investigate-the-docker-images-failing-qualification.png
diff --git a/...torials/working-with-components/manually-setting-the-systemd-units-property.png b/...torials/working-with-components/manually-setting-the-systemd-units-property.png
diff --git a/...c/tutorials/working-with-components/observe-the-docker-images-qualification.png b/...c/tutorials/working-with-components/observe-the-docker-images-qualification.png
diff --git a/...tutorials/working-with-components/observe-the-new-system-units-unit-0-entry.png b/...tutorials/working-with-components/observe-the-new-system-units-unit-0-entry.png
diff --git a/...-with-components/observe-the-systemd-units-property-of-the-butane-component.png b/...-with-components/observe-the-systemd-units-property-of-the-butane-component.png
diff --git a/app/docs/src/tutorials/working-with-components/veiw-the-debugging-information.png b/app/docs/src/tutorials/working-with-components/veiw-the-debugging-information.png
diff --git a/app/docs/src/tutorials/working-with-components/viewing-generated-code.png b/app/docs/src/tutorials/working-with-components/viewing-generated-code.png
diff --git a/app/docs/src/tutorials/working-with-components/viewing-large-properties.png b/app/docs/src/tutorials/working-with-components/viewing-large-properties.png
diff --git a/app/docs/src/writing-docs.md b/app/docs/src/writing-docs.md
@@ -0,0 +1,37 @@
+# Writing documentation
+
+We're so glad you want to write some documentation! Here are some guidelines to help you along the way.
+
+## Professional Voice
+
+Regardless of the type of documentation you are writing, the voice should be professional and simple. A great piece of documentation has should be at or below a high school reading level. Favor gender neutral language (you/your/they/them).
+
+## No Slang, Humor, or Sarcasm
+
+Avoid slang, humor, and sarcasm. It's more fun to write, but it's easy to get lost in translation.
+
+## No Marketing
+
+Documentation is not the place for marketing copy. People come to the documentation to learn how to use the product, or solve their problems. Not to be sold on why it's valuable.
+
+## Types of Documentation
+
+There are four different types of documentation, each with their own purpose and flavor.
+
+### Tutorials
+
+These teach people how to use System Initiative through using System Initiative. Their goal is to inform people about how to use the functionality of System Initiative. A good tutorial requires as little outside knowledge as possible to show the task. With that in mind, examples should still be realistic - avoid synthetic examples that exist purely to demonstrate functionality.
+
+All tutorials should have a video walkthrough recorded. If you aren't a System Initiative employee, don't worry - go ahead and write the tutorial, and we'll record the video.
+
+Each section of the tutorial should have an image, highlighting the most important interaction for the section.
+
+## Images and Screen Shots
+
+We use [Flameshot](https://flameshot.org/) to produce our screen shots.
+
+Configure your colorpicker to have a color preset for #ffd41e. When making up a screenshot, make sure you select this color by right-clicking the resulting image before you mark it up.
+
+Full screen shots should include the application, but not the browser.
+
+Name the images after the section they reference, in a sub-folder named after the documentation they are used in. For example, the image for the `Add a Secret` section of the [Getting Started](/tutorials/getting-started) tutorial is named `getting-started/add-a-secret.png`.
diff --git a/app/web/src/components/AssetDiffDetails.vue b/app/web/src/components/AssetDiffDetails.vue
@@ -7,31 +7,27 @@
 
     <template v-if="diffReqStatus.isSuccess && selectedComponentDiff">
       <div class="absolute inset-xs">
-        <template v-if="selectedComponent.changeStatus === 'unmodified'">
+        <template v-if="selectedComponentDiff.diffs[0]?.code">
+          <!-- what to do about multiple diffs? -->
           <CodeViewer
-            v-if="selectedComponentDiff.current.code"
-            :code="selectedComponentDiff.current.code"
-            :codeLanguage="selectedComponentDiff.current.language"
+            :code="selectedComponentDiff.diffs[0]?.code"
+            :codeLanguage="selectedComponentDiff.diffs[0]?.language"
             :allowCopy="false"
           >
             <template #title>
-              <span class="text-lg">Current</span>
+              <span class="text-lg">Diff</span>
             </template>
           </CodeViewer>
-          <div v-else class="w-full text-center text-xl text-neutral-400 p-sm">
-            No Code
-          </div>
         </template>
         <template v-else>
-          <!-- what to do about multiple diffs? -->
           <CodeViewer
-            v-if="selectedComponentDiff.diffs[0]?.code"
-            :code="selectedComponentDiff.diffs[0]?.code"
-            :codeLanguage="selectedComponentDiff.diffs[0]?.language"
+            v-if="selectedComponentDiff.current.code"
+            :code="selectedComponentDiff.current.code"
+            :codeLanguage="selectedComponentDiff.current.language"
             :allowCopy="false"
           >
             <template #title>
-              <span class="text-lg">Diff</span>
+              <span class="text-lg">Current</span>
             </template>
           </CodeViewer>
           <div v-else class="w-full text-center text-xl text-neutral-400 p-sm">

diff --git a/app/web/src/components/AttributesPanel/AttributesPanelItem.vue b/app/web/src/components/AttributesPanel/AttributesPanelItem.vue
@@ -536,8 +536,8 @@
       </div>
       <div class="attributes-panel-item__view-value-modal-code-wrap">
         <template v-if="widgetKind === 'textArea'">
-          <pre class="attributes-panel-item__edit-value-modal__view-text">
-          {{ newValueString }}
+          <pre class="attributes-panel-item__edit-value-modal__view-text"
+            >{{ newValueString }}
           </pre>
         </template>
         <template v-else-if="widgetKind === 'codeEditor'">