Components Documentation

README.md

@@ -5,27 +5,6 @@ Work in progress implementation of [SHIP-0031][SHIP-0031].
 
 ## Contributing
 
-To work on this project, consider the following `Makefile` targets:
-
-```bash
-# builds the application
-make
-
-# run unit-tests
-make test-unit
-
-# run end-to-end tests
-make test-e2e
-
-# deploy against the controller
-make deploy IMAGE_BASE='ghcr.io/...'
-```
-
-To work on this project you need the following tools installed:
-
-- GNU/Make
-- Helm
-- KO
-- Kubernetes (`kubectl`)
+Please consider the [primary components](./docs/components.md), also how to [build and test](./docs/building.md) this repository.
 
 [SHIP-0031]: https://github.com/shipwright-io/community/blob/main/ships/0031-shipwright-trigger.md

docs/building.md

@@ -0,0 +1,82 @@
+Building and Testing Shipwright Triggers
+----------------------------------------
+
+This document describes how to build and test this project, to work on this project you need the following tools installed:
+
+- [GNU/Make][gnuMake]
+- [Helm][helmInstall]
+- [KO][koBuild]
+
+ The automation necessary to accomplish the objective is concentrated on the [`Makefile`](../Makefile), the organization of each task is defined by the targets. Targets are the entrypoint for the project automation tasks, the most important are described below.
+
+# Building
+
+To compile the project run `make` without any arguments, i.e.:
+
+```bash
+make
+```
+
+# Testing
+
+Project testing is subdivided as [unit](#unit) and [end-to-end](#e2e) tests, in order to run all tests in the project use the `test` target, i.e.:
+
+```bash
+make test
+```
+
+Please consider the section below to better understand requirements for end-to-end tests.
+
+## Unit
+
+Unit tests will be exercised by the `test-unit` target. For instance:
+
+```bash
+make test-unit
+```
+
+During development you might want to narrow down the scope, this can be achieved using the `ARGS` variable, the flags informed are appended on the [`go test`](goTest) command.
+
+For example, narrowing down `TestInventory` function:
+
+```bash
+make test-unit ARGS='-run=^"TestInventory$$"'
+```
+
+## E2E
+
+End-to-end tests (E2E) will assert the project features against the *real* dependencies, before running the `test-e2e` target you will need to provide the Shipwright Build instance, including its dependencies. Please follow this [documentation section](shpTryIt) first.
+
+With the dependencies in place, run:
+
+```bash
+make test-e2e
+```
+
+Please consider the [GitHub Actions](#github-actions) section below to have a more practical way of running E2E tests in your own laptop.
+
+## GitHub Actions
+
+Continuous integration (CI) [tests](../.github/workflows/test.yaml) are managed by GitHub Actions, to run these jobs locally please consider [this documentation section][shpSetupContributing] which describes the dependencies and settings required.
+
+After you're all set, run the following target to execute all jobs:
+
+```bash
+make act
+```
+
+ The CI jobs will exercise [unit](#unit) and [end-to-end](#e2e) tests sequentially, alternatively you may want to run a single suite at the time, that can be achieved using `ARGS` (on `act` target).
+
+ Using `ARGS` you can run a single `job` passing flags to [act][nektosAct] command-line. For instance, in order to only run [unit tests](#unit) (`make test-unit`):
+
+```bash
+make act ARGS="--job=test-unit"
+```
+
+[gnuMake]: https://www.gnu.org/software/make
+[goTest]: https://pkg.go.dev/cmd/go/internal/test
+[helmInstall]: https://helm.sh/docs/intro/quickstart/#install-helm
+[koBuild]: https://github.com/ko-build/ko
+[nektosAct]: https://github.com/nektos/act
+[shpSetupContributing]: https://github.com/shipwright-io/setup/blob/main/README.md#contributing
+[shpTryIt]: https://github.com/shipwright-io/build#try-it

docs/components.md

@@ -0,0 +1,40 @@
+Components
+----------
+
+This document describes the major components present in this application and organized in as packages in the [`pkg`](../pkg) directory.
+
+<p align="center">
+	<img alt="Shipwright Triggers components" src="./assets/components.drawio.png" />
+</p>
+
+# Build Inventory
+
+The inventory is the central component of Shipwright Triggers, it stores all the Build instances organized in a way that allows searching for types of triggers, depending on the Inventory client.
+
+For example, the WebHook Handler will always search for Builds based on the Git repository URL, the type of event (Push or PullRequest), and the branch names. In other hand, the other Controllers will query the inventory based on the `.objectRef` attribute instead.
+
+As you can see on the diagram above, almost all components are interacting with the Inventory using the specialized query methods `SearchForGit` and `SearchForObjectRef`.
+
+# WebHook Handler
+
+The WebHook handler is a simple HTTP server implementation which receives requests from the outside, and after processing the event, searches over Builds that should be activated. The search on the inventory happens in the same fashion as the controllers, however uses `SearchForGit` method.
+
+This type of `SearchForGit` is meant to match the repository URL, the type of event and the branches affected. For instance, the WebHook event can have different types, like Push or PullRequest and plus the branch affected.
+
+# Kubernetes Controllers
+
+## Shipwright Build Controller
+
+The Builds are added or removed from the Inventory through the Build Controller, responsible to reflect all Shipwright Build resources into the Inventory. On adding new entries, the Build is prepared for the subsequent queries.
+
+## Tekton Run Controller
+
+Watches for Tekton Run instances referencing Shipwright Builds, when a new instance is created it creates a new BuildRun. The controller also watches over the BuildRun instance, in order to reflect the status back to the Tekton Run parent.
+
+The Tekton Run instances are part of the Custom-Tasks workflow, everytime Tekton finds a TaskRef resource outside of Tekton's scope, it creates a Run instance with the coordinates. In other words, to extend Tekton's functionality third party applications must watch and interact with those objects.
+
+## Tekton PipelineRun Controller
+
+The controller for PipelineRun instances is meant to react when a Pipeline reaches the desired status, so upon changes on the resource the controller checks on the inventory if there are triggers configured for the specific resource in question, in the desired status.
+
+Upon the creation of a BuildRun instance, the PipelineRun object is labeled for the controller to be able to avoid reprocessing.