doc(KONFLUX-5695): explain Snapshots and their usage

* Added Working with Snapshots page which
  explains the meaning/usage of snapshot and each field
* Grouped Snapshot-related pages in a separate
  subdirectory in the integration testing page

Signed-off-by: dirgim <[email protected]>

rh-pre-commit.version: 2.2.0
rh-pre-commit.check-secrets: ENABLED

Author: dirgim

docs/modules/ROOT/pages/how-tos/_nav.adoc

@@ -24,9 +24,11 @@
 **** xref:how-tos/testing/integration/editing.adoc[Editing integration tests]
 **** xref:how-tos/testing/integration/debugging.adoc[Debugging an integration test]
 **** xref:how-tos/testing/integration/rerunning.adoc[Rerunning an integration test]
-**** xref:how-tos/testing/integration/override-snapshots.adoc[Creating an override snapshot]
-**** xref:how-tos/testing/integration/group-snapshots.adoc[Creating a group snapshot]
 **** xref:how-tos/testing/integration/choosing-contexts.adoc[Choosing when to run certain Integration Tests]
+**** Snapshots
+***** xref:how-tos/testing/integration/snapshots/working-with-snapshots.adoc[Working with Snapshots]
+***** xref:how-tos/testing/integration/snapshots/override-snapshots.adoc[Creating an override snapshot]
+***** xref:how-tos/testing/integration/snapshots/group-snapshots.adoc[Creating a group snapshot]
 **** Third Parties
 ***** xref:how-tos/testing/integration/third-parties/testing-farm.adoc[Testing with Testing Farm]
 ** xref:how-tos/metadata/index.adoc[Inspecting provenance and attestations]

docs/modules/ROOT/pages/how-tos/testing/index.adoc

@@ -34,6 +34,6 @@ Integration tests ensure that all components within an application are able to w
 
 As with build-time tests, you can also create your own integration tests.  To add your own test that runs on all components of an application, xref:./integration/creating.adoc[create a custom integration test].
 
-The integration service provides users with the ability to reset their component's Global Candidate List to a desired state with a manually created `override`, you can xref:./integration/override-snapshots.adoc[create an override snapshot] and provide a valid container image for component to reset the component's Global Candidate List.
+The integration service provides users with the ability to reset their component's Global Candidate List to a desired state with a manually created `override`, you can xref:how-tos/testing/integration/snapshots/override-snapshots.adoc[create an override snapshot] and provide a valid container image for component to reset the component's Global Candidate List.
 
 While these tests are triggered after new artifacts are built (for example after build pipelines have successfully completed), their execution can be retriggered without building new artifacts. This process is described in xref:./integration/rerunning.adoc[retriggering integration tests].

docs/modules/ROOT/pages/how-tos/testing/integration/choosing-contexts.adoc

@@ -12,12 +12,12 @@ The full list of supported contexts is:
 * "pull_request" - runs the integration test in case of the Snapshot being created for a `pull request` event
 * "push" - runs the integration test in case of the Snapshot being created for a `push` event
 * "override" - runs the integration test for an `override` Snapshot
-** See more in xref:how-tos/testing/integration/override-snapshots.adoc[Creating an override snapshot]
+** See more in xref:how-tos/testing/integration/snapshots/override-snapshots.adoc[Creating an override snapshot]
 * "disabled" - disables the execution of the given integration test if it's the only context that's defined
 ** This can be useful if the scenario in question needs to only be executed manually, see more about running
 integration tests manually in xref:how-tos/testing/integration/rerunning.adoc[Rerunning an integration test]
 * "group" - runs the integration test for a `group` Snapshot
-** See more in xref:how-tos/testing/integration/group-snapshots.adoc[Creating a group snapshot]
+** See more in xref:how-tos/testing/integration/snapshots/group-snapshots.adoc[Creating a group snapshot]
 
 +
 NOTE: When multiple contexts are defined, the IntegrationTestScenario will execute if any of the specified contexts match the snapshot. This approach ensures that the test runs as long as at least one context applies, without requiring all defined contexts to be met.

docs/modules/ROOT/pages/how-tos/testing/integration/group-snapshots.adoc renamed to docs/modules/ROOT/pages/how-tos/testing/integration/snapshots/group-snapshots.adoc

@@ -37,7 +37,7 @@ spec:
 <1> The label `test.appstudio.openshift.io/type: override` that indicates this is an `override` snapshot.
 <2> The component name you will reset its Global Candidate List.
 <3> The container image with valid digest you will reset the component <2> to.
-<4> Optional, but may cause an Enterprise Contract check to fail if it's incorrect or missing. The component source containing the git url and revision that the container image was built from.
+<4> Optional, but may cause an Enterprise Contract check to fail if it's incorrect or missing. The component source containing the git URL and revision that the container image was built from.
 
 . Save the .yaml file and add the snapshot.yaml by running the following command:
 +

docs/modules/ROOT/pages/how-tos/testing/integration/override-snapshots.adoc renamed to docs/modules/ROOT/pages/how-tos/testing/integration/snapshots/override-snapshots.adoc

@@ -0,0 +1,79 @@
+= Working with Snapshots
+
+In {ProductName}, the central resource which is created, tested and released as a single unit is called the Snapshot.
+
+== What is a Snapshot?
+The Snapshot is a custom resource that contains the list of all Components of an {ProductName} Application with their Component Image digests and their sources. Once created, the list of Components with their images is immutable. The Integration service updates the status of the resource to reflect the testing outcome. The Release service releases the contents of the Snapshot via Release pipelines.
+
+Example Snapshot resource contents::
+[source]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: Snapshot
+metadata:
+  name: snapshot-sample <.>
+  namespace: ws-sample-tenant <.>
+spec:
+  application: application-sample <.>
+  components:
+    - name: component-sample <.>
+      containerImage: quay.io/redhat-user-workloads/ws-sample-tenant/application-sample/component-sample@sha256:0db0a473a6abf5c15c424ab07cfbd5c40c06622fe648d4fe6a6b6abc224a0d0c <.>
+      source: <.>
+        git:
+          url: https://github.com/sample-org/sample-repo
+          revision: fa8b89274a61ef0f1c257b7a84c37aa2ec844109
+----
+<.> The name of the Snapshot resource.
+<.> The namespace where the Snapshot exists. It should correspond to the user's tenant namespace.
+<.> The Application that the Snapshot belongs to.
+<.> The name of the individual Component of the Application.
+<.> The full image pull specification for the container image. The images need to be referenced by digest.
+<.> The component source containing the git URL and revision that the component's container image was built from.
+
+== Working with manual Snapshots
+
+Aside from the Snapshots which are created and processed automatically by the {ProductName} services, it is also possible to create manual Snapshots which can then be tested and released if they conform to the users requirements.
+
+== Prerequisites
+- You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
+- You have an existing managed workspace such as `ws-sample`, an application such as `application-sample` and a component such as `component-sample`.
+
+== Procedures
+To create a manual snapshot, complete the following steps:
+
+. Identify the application and component images which you want tested and released.
+. In your preferred IDE, create a snapshot definition in a `.yaml` file.
+.. For example contents, see the example Snapshot section above.
+. Save the .yaml file and add the snapshot.yaml by running the following command:
++
+[source,terminal]
+----
+$ kubectl create -f snapshot.yaml -n ws-sample-tenant
+----
+This command adds the Snapshot to your workspace and integration service will test and potentially trigger a release of the Snapshot.
+
+== Verification
+After integration service processes the created manual snapshot, you may verify snapshot and component by the following steps:
+
+. Check if Snapshot passed all tests by getting the `.Status.Conditions.AppStudioTestSucceeded` condition with the following command:
++
+[source,terminal]
+----
+$ kubectl get snapshot snapshot-sample -n ws-sample-tenant -o yaml | yq '.status.conditions.[] | select(.type =="AppStudioTestSucceeded")'
+lastTransitionTime: "2025-01-21T09:18:00Z"
+message: All Integration Pipeline tests passed
+reason: Passed
+status: "True"
+type: AppStudioTestSucceeded
+----
+. If you have xref:/advanced-how-tos/releasing/create-release-plan.adoc[automatic Releases defined], you can check if Snapshot was auto-released getting the `.Status.Conditions.AutoReleased` condition with the following command:
++
+[source,terminal]
+----
+$ kubectl get snapshot snapshot-sample -n ws-sample-tenant -o yaml | yq '.status.conditions.[] | select(.type =="AutoReleased")'
+lastTransitionTime: "2025-01-21T09:18:01Z"
+message: The Snapshot was auto-released
+reason: AutoReleased
+status: "True"
+type: AutoReleased
+----