refactor: improves documentation with feedback (#65)

actions/setup/README.md

@@ -1,4 +1,4 @@
-# run
+# setup
 
 > Performs required steps to setup CI
 

docs/mkdocs.yml

@@ -11,9 +11,9 @@ nav:
   - Style Guide: style.md
   - Reference:
       - reference/index.md
+      - Workflows: reference/workflows.md
       - Actions: reference/actions.md
       - Targets: reference/targets.md
-      - Workflows: reference/workflows.md
       - UDCs: reference/udc.md
   - Appendix:
       - Earthly: appendix/earthly.md

docs/src/onboarding/index.md

@@ -29,7 +29,8 @@ This promotes self-service and establishes a clear boundary of ownership whereby
 maintaining a single file in their subproject.
 
 The CI process is well-documented and troubleshooting unexpected errors only requires knowledge of Earthly and GitHub Actions.
-All of the code is contained in a single open-source repository and contributions are welcome.
+All of the code is contained in a single [open-source repository](https://github.com/input-output-hk/catalyst-ci) and contributions
+are welcome.
 The remainder of the overview section will focus on discussing some of these concepts in more detail.
 
 ### Discovery

docs/src/reference/targets.md

@@ -122,7 +122,7 @@ This target is the final target that is run (and must pass) before artifacts are
 
 The `publish` target is responsible for building and publishing a container image to image registries.
 This target should be used when a subproject needs to produce and publish a container image.
-The CI will execute this target after the `check` target, assuming it passes.
+The CI will execute this target after the `test` target, assuming it passes.
 
 ### How it Works
 
@@ -151,10 +151,10 @@ The CI will automatically handle auxiliary tasks like image scanning and/or sign
 ## Release
 
 The `release` target is responsible for building and releasing artifacts to GitHub.
-This target should be used when a subproject produces artifacts (i.e. a binary) that is appropriate to include in a GitHub release.
+This target should be used when a subproject produces artifacts (i.e. a binary) that are appropriate to include in a GitHub release.
 For example, a subproject may produce a binary that is intended to be used directly (i.e. a CLI) or it may produce a set of files
 that end-users need access to during a release cycle.
-The CI will execute this target after the `check` target, assuming it passes.
+The CI will execute this target after the `test` target, assuming it passes.
 
 ### How it Works
 
@@ -164,7 +164,7 @@ If the commit that triggered the CI does not contain a git tag, then the CI will
 This allows end-users to validate that their release artifacts build as expected without relying on a release cycle.
 
 If instead the commit contains a git tag, then the resulting artifacts are compressed into a single tarball and uploaded as an
-artifact of the GitHub Action job.
+artifact of the individual GitHub Action job.
 The compression happens regardless of whether a single or multiple artifacts were produced.
 After the `release` target has been run for *every* subproject, the produced artifacts from all subprojects are then attached into a
 single GitHub release for the given git tag (i.e., `1.0.0`).

docs/src/reference/workflows.md

@@ -22,9 +22,9 @@ These individual actions will be discussed in the next section.
 Since most of the workflow logic was discussed in the previous section, this section will refrain from duplicating that effort and
 instead focus on how to use the workflows (including covering their inputs).
 
-## Common Inputs
+### Common Inputs
 
-### AWS
+#### AWS
 
 Most of the workflows accept an optional AWS role and region.
 The workflow will attempt to automatically authenticate and assume the role prior to performing any other steps.
@@ -37,7 +37,7 @@ The only other case where AWS authentication is required is during the `publish`
 | aws_role_arn | string | The ARN of the AWS role that will be assumed by the workflow | No       | `""`    |
 | aws_region   | string | The AWS region that will be used by the workflow             | No       | `""`    |
 
-### Earthly Runner
+#### Earthly Runner
 
 As noted above, Catalyst CI uses a remote Earthly runner in order to maximize cache hits.
 As a result, all workflows that interact with Earthly will accept optional inputs describing the address of the runner as well as
@@ -51,7 +51,7 @@ and interact with the remote Earthly runner.
 | earthly_runner_secret  | string | The ID of the AWS secret holding Earthly runner credentials | No       | `""`     |
 | earthly_version        | string | The version of Earthly to use.                              | No       | `latest` |
 
-### CLI
+#### CLI
 
 Most workflows utilize the custom CLI provided by the Catalyst CI repository.
 It's possible to specify a specific version of the CI to be installed (as opposed to the default of installing the latest).
@@ -116,16 +116,16 @@ These artifacts are then compressed and ultimately uploaded as artifacts for the
 ## Deploy
 
 The deploy workflow is responsible for deploying services to the Catalyst `dev` cluster when new container images are produced.
-It checks out the code from the Catalyst gitops repository and uses the custom `merge` GitHub Action to merge the new image tags
-into the deployment files.
-The changes are then committed, causing the `dev` environment to deploy the newly produced images.
+It checks out the code from a private Project Catalyst repository and uses the custom `merge` GitHub Action to merge the new image
+tags into the repository files.
+The changes are then committed, which triggers the `dev` environment to deploy the newly produced images.
 
 ### Inputs
 
 | Name            | Type   | Description                                              | Required | Default                          |
 | --------------- | ------ | -------------------------------------------------------- | -------- | -------------------------------- |
-| deployment_repo | string | The URL of the repository containing deployment code     | No       | `input-output-hk/catalyst-world` |
-| environment     | string | The target environment to deploy to                      | No       | `dev`                            |
+| deployment_repo | string | The URL of the repository to merge with                  | No       | `input-output-hk/catalyst-world` |
+| environment     | string | The target environment to deploy                         | No       | `dev`                            |
 | images          | string | A newline separated list of image names to deploy        | Yes      | N/A                              |
 | tag             | string | The image tag to deploy                                  | Yes      | N/A                              |
 | token           | string | A Github token with access to the deployment repository. | Yes      | N/A                              |

docs/src/style.md

@@ -35,9 +35,19 @@ check:
     # analysis checks.
 
 build:
-    FROM +build
+    FROM +src
+    SAVE ARTIFACT ./artifact
     # This target is used by the CI and should be used to build the project.
 
+package:
+    FROM +build
+    COPY ./artifact pkg
+    COPY ../other_project+build/artifact pkg
+    # This target is uncommon in most Earthfiles, however, certain subprojects
+    # have dependencies on other subprojects which should be defined in this
+    # target. We define it here to serve as an example, however, we don't use it
+    # in future steps.
+
 test:
     FROM +build
     # This target is used by the CI and should be used to running all tests that
@@ -49,6 +59,9 @@ release:
     # This target is used by the CI and should use `SAVE ARTIFACT` to save the
     # result of the build step in cases where the artifact should be included
     # with the GitHub release (i.e., things that are self-contained like CLIs).
+    # Note that in many cases, this will look identical to the `build` step.
+    # However, to the CI, these are two distinct steps. Also, in some cases, the
+    # release target may have additional steps to perform.
 
 publish:
     FROM <base image>
@@ -109,6 +122,14 @@ DO github.com/input-output-hk/catalyst-ci/earthly/udc+NAME:tag
 Where `tag` is the git tag.
 This ensures that upstream changes do not incidentally break builds.
 
+### Avoid `LOCALLY`
+
+The `LOCALLY` directive causes Earthly to execute all commands on the local machine instead of inside of a container.
+This directive is useful for troubleshooting, but otherwise it fits a very small number of use cases.
+The official Earthly best practices document recommends against using this directive in most cases.
+It can be destructive, complete with different results each time, and by default is not run during CI.
+For these reasons, usage of it should be avoided where possible.
+
 ### Avoid `--no-cache`
 
 The `RUN` command allows passing a `--no-cache` flag which will force Earthly
@@ -120,7 +141,18 @@ this flag and all caching proceeds to immediately stop.
 To prevent this, the `--no-cache` should be avoided at all times.
 The only acceptable time to use it is for debugging purposes.
 
-### Prefer UDCs
+### Keep `build` as the source of truth for build artifacts
+
+The `build` target should be used as the single source of truth for building a given subproject's artifacts.
+The target may call other targets to accomplish the build, however, the `build` target should contain the authoritative source.
+Practically, this means that a subproject should only have one way to build it (via the `build` target).
+
+In addition to the above, targets which rely on built artifacts should always reference `build`.
+This can be through inheriting from it or by directly copying artifacts.
+The main point is that a subproject should not have multiple builds scattered in various places.
+Each subproject has an authoritative `build` target that *all* targets use when fetching build artifacts.
+
+### Prefer User Defined Commands (UDCs)
 
 The primary purpose of a UDC is to reduce boilerplate and promote reusing common workflows.
 Many build patterns tend to be repetitive.