expand description section of readme; document release process

README.md

@@ -4,12 +4,51 @@
 [![Continuous Integration](https://github.com/project-codeflare/appwrapper/actions/workflows/CI.yaml/badge.svg)](https://github.com/project-codeflare/appwrapper/actions/workflows/CI.yaml)
 
 An AppWrapper is a collection of Kubernetes resources than can be jointly queued
-and dispatched using [Kueue](https://kueue.sigs.k8s.io).
+and admitted using [Kueue](https://kueue.sigs.k8s.io).
 
 ## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
 
-The lifecycle of an AppWrapper instance is depicted in a [state transition diagram](docs/state-diagram.md).
+Kueue has a well-developed pattern for Kueue-enabling a Custom
+Resource Definition and its associated operator. Following this pattern
+allows the resulting operator to smoothly run alongside the core Kueue
+operator. The pattern consists of three main elements: an Admission
+Controller, a Workload Controller, and a Framework Controller.
+
+#### Admission Controller
+
+Kueue requires the definition of an Admission Controller that ensures
+that the `.spec.suspend` field of newly created AppWrapper instances is
+set to true. We also leverage the Admission Controller to ensure that
+the user creating the AppWrapper is also entitled to create the contained resources
+and to validate AppWrapper-specific invariants.
+
+See [appwrapper_webhook.go](./internal/controller/appwrapper_webhook.go)
+for the implementation.
+
+#### Workload Controller
+
+An instantiation of Kueue’s GenericReconciller along with an
+implementation of Kueue’s GenericJob interface for the AppWrapper
+CRD. As is standard practice in Kueue, this controller will watch
+AppWrapper instances and their owned Workload instances to reconcile
+the two. This controller will make it possible for Kueue to suspend,
+resume, and constrain the placement of the AppWrapper. It will report
+the status of the AppWrapper to Kueue.
+
+See [workload_controller.go](./internal/controller/workload_controller.go)
+for the implementation.
+
+#### Framework Controller
+
+A standard reconciliation loop that watches AppWrapper instances and
+is responsible for all AppWrapper-specific operations including
+creating, monitoring, and deleting the wrapped resources in response
+to the modifications of the AppWrapper instance’s specification and
+status made by the Workload Controller described above.
+
+This [state transition diagram](docs/state-diagram.md) depicts the
+lifecycle of an AppWrapper; the implementation is found in
+[appwrapper_controller.go](./internal/controller/appwrapper_controller.go).
 
 ## Getting Started
 

docs/release_instructions.md

@@ -0,0 +1,20 @@
+## Release Instructions
+
+The entire AppWrapper release process is automated via GitHub actions.
+
+To make a release, simply create a new release tag (vX.Y.Z) and push the
+tag to the main branch.  This will trigger the `release` workflow which
+will:
+   + build, tag, and push images to [quay.io/ibm/appwrapper](https://quay.io/repository/ibm/appwrapper)
+   + generate the install.yaml for the release
+   + create a [GitHub release](https://github.com/project-codeflare/appwrapper/releases) that contains the install.yaml
+
+
+## Installing from a Release
+
+If you have a Kubernetes cluster with Kueue installed, you can install
+a release of the AppWrapper CRD and operator simply by doing:
+```sh
+kubectl apply --server-side -f https://github.com/project-codeflare/appwrapper/releases/download/RELEASE_VERSION/install.yaml
+```
+Replace `RELEASE_VERSION` in the above URL with an actual version, for example `v0.3.2`.