docs: unify styling of implementing folder (#2398)

(cherry picked from commit 70cff9f)
Signed-off-by: realanna <anna.reale@dynatrace.com>

docs/content/en/contribute/software/dev-environ/_index.md

@@ -1,20 +1,81 @@
 ---
-title: Set up the development environment
-description: How to set up an environment to develop and test Keptn software
+title: Software development environment
+description: How to set up and use the development environment to develop and test Keptn software
 weight: 30
 ---
 
+This page gives instructions and hints for setting up a development environment
+and then develop, test, and deploy your software changes in that environment.
+This material was presented at the
+11 September 2023 New Contributors meeting.
+You can view the video
+[here](https://www.youtube.com/watch?v=UcmULstMYXQ).
+
+To prepare to contribute to the Keptn project, we recommend that you:
+
+* Study the [Keptn documentation](https://lifecycle.keptn.sh/docs/)
+  to understand what Keptn does and how it works.
+* Familiarize yourself with the
+  [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit)
+  repository, which is the primary repository for
+  Keptn software and documentation.
+  In particular, study the sections for the four main Keptn components:
+
+  * [lifecycle-operator](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator)
+  * [metrics-operator](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator)
+  * [scheduler](https://github.com/keptn/lifecycle-toolkit/tree/main/scheduler)
+  * [klt-cert-manager](https://github.com/keptn/lifecycle-toolkit/tree/main/klt-cert-manager)
+
+  Each of these is described in the
+  [Architecture](../../../docs/architecture/)
+  section of the documentation
+  and most include a *README* file with more information.
+* Study the material in
+  [Technologies and concepts you should know](../../general/technologies).
+* Create an account for yourself on
+  [GitHub](https://github.com)
+  if you do not already have an account.
+* Set up a fork of the [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit) repository to use with your development.
+
+## View repository
+
+When you view the
+[lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit)
+repository, you see that Keptn is composed of multiple components,
+each of which is discussed in the Architecture
+[Architecture](../../../docs/architecture/)
+documentation:
+
+* Three Kubernetes operators
+  * `metrics-operator`
+  * `lifecycle-operatory`
+  * `cert-manager`
+* Keptn `scheduler`
+
+At the top level of the repository,
+you also see the `runtimes` directory.
+This defines the runners that you can use when defining
+tasks to be run either pre- or post-deployment.
+These are discussed in
+[Runners and containers](../../../docs/implementing/tasks.md#runners-and-containers).
+
+## Install software
+
 To test and develop software for the Keptn project,
 you need to install the following on your system:
 
 * [**Docker**](https://docs.docker.com/get-docker/): a tool for containerization,
-which allows software applications to run in isolated environments
-and makes it easier to deploy and manage them.
+  which allows software applications to run in isolated environments
+  and makes it easier to deploy and manage them.
 * A Kubernetes cluster running an appropriate version of Kubernetes.
   See [Supported Kubernetes versions](../../../docs/install/reqs.md/#supported-kubernetes-versions)
   for details.
-  If you need to set up a local Kubernetes cluster
-  we recommend Kubernetes-in-Docker(kind).
+  Most contributors create a local
+  Kubernetes-in-Docker(KinD) cluster.
+  This is adequate for developing software for Keptn.
+  See
+  [Kubernetes cluster](../../../docs/install/k8s.md/#create-local-kubernetes-cluster)
+  for instructions.
 * [**kubectl**](https://kubernetes.io/docs/tasks/tools/):
   a command-line interface tool used for deploying
   and managing applications on Kubernetes clusters.
@@ -24,3 +85,97 @@ and makes it easier to deploy and manage them.
 * [**Helm**](https://helm.sh/): a package manager for Kubernetes
   that simplifies the deployment and management of applications
   on a Kubernetes cluster.
+* [**Go-lang**](https://go.dev/): the language used to code the Keptn software.
+
+## First steps
+
+1. Follow the instructions in
+   [Fork and clone the repository](../../general/git/fork-clone/)
+   to get a local copy of the software.
+
+1. Keptn provides a tool that deploys the development version of the software
+   on your Kubernetes cluster and pushes the built image to your private repository.
+   You identify your private repository with the `RELEASE_REGISTRY=` argument
+   and can add any `TAG` arguments you like.
+   For example, the following command builds the environment
+   and pushes the image to the `docker.io/exampleuser` github repository:
+
+   ```shell
+   make build-deploy-dev-environment RELEASE_REGISTRY=docker.io/exampleuser TAG=main
+   ```
+
+   The build commands are defined in the
+   [Makefile](https://github.com/keptn/lifecycle-toolkit/blob/main/Makefile)
+   located in the root directory of your clone.
+   This file includes a number of environment variables
+   that can be specified as required.
+
+1. After this runs, verify that pods are running on your Kubernetes cluster
+   for the four components of the product.
+
+## Code your changes
+
+You are now ready to make your changes to the source code.
+
+1. Follow the instructions in
+   [Create local branch](../../general/git/branch-create/)
+   to create a branch for your changes.
+
+1. Make your changes to the appropriate component.
+
+1. Deploy the component you modified and push the image to your private Github repository.
+   Note that you do not need to rebuild all components,
+   only the one you modified.
+   For example, if your modifications are to the `metrics-operator`, run:
+
+   ```shell
+   make build-deploy-metrics-operator RELEASE_REGISTRY=docker.io/exampleuser TAG=my-feature
+   ```
+
+## Testing
+
+Keptn includes a set of tests that are run on each PR that is submitted.
+We require that all changes pass
+unit tests, component tests, end-to-end tests, and integration tests
+before you create a PR with your changes.
+
+If your change introduces a new feature,
+you may need to update the test suites to cover your changes.
+These tests use basic go-library, Ginkgo or KUTTL tests.
+You can ask the maintainers to tell you where to put your additional test data.
+
+Tests are run on your local machine.
+Study the detailed log that is produced to identify why the test failed.
+Study these errors, modify your code, and rerun the test until it passes.
+
+1. Use your IDE to run unit tests on your code.
+
+1. Run the integration tests from the root directory of your clone:
+
+   ```shell
+   make integration-test-local
+   ```
+
+   `integration-test-local` cleans up after the test.
+
+1. From the `lifecycle-operator` directory, run the component test:
+
+   ```shell
+   make component-test
+   ```
+
+1. From the `lifecycle-operator` directory, run the end-to-end tests:
+
+   ```shell
+   make e2e-test
+   ```
+
+## Create and manage the PR
+
+When all the tests have passed,
+you can follow the instructions in
+[Create PR](../../general/git/pr-create/)
+to create your PR.
+Be sure to monitor your PR as discussed in
+[PR review process](../../general/git/review/)
+until it is merged.

docs/content/en/docs/architecture/components/metrics-operator.md

@@ -27,7 +27,7 @@ so they are compatible with the Kubernetes
 (HPA), which enables the horizontal scaling of workloads
 based on metrics collected from multiple observability platforms.
 See
-[Using the HorizontalPodAutoscaler](../../implementing/evaluatemetrics.md/#using-the-horizontalpodautoscaler)
+[Using the HorizontalPodAutoscaler](../../implementing/evaluatemetrics.md#using-the-horizontalpodautoscaler)
 for instructions.
 
 The Metrics Operator consists of the following components:

docs/content/en/docs/architecture/components/scheduler.md

@@ -23,7 +23,7 @@ to gate Pods until the required deployment checks pass.
 When you apply a workload to a K8s cluster,
 the Mutating Webhook checks each Pod for annotations
 to see if it is annotated with
-[Keptn specific annotations](../../implementing/integrate/_index.md#basic-annotations).
+[Keptn specific annotations](../../implementing/integrate.md#basic-annotations).
 If the annotations are present, the Webhook adds a gate to the Pod called `keptn-prechecks-gate`.
 This spec tells the Kubernetes scheduling framework
 to wait for  the Keptn checks before assigning the pod to a node.
@@ -64,7 +64,7 @@ a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/schedu
 ### How does the Keptn Scheduler works
 
 Firstly the Mutating Webhook checks for annotations on Pods to see if it is annotated with
-[Keptn specific annotations](../../implementing/integrate/#basic-annotations).
+[Keptn specific annotations](../../implementing/integrate.md#basic-annotations).
 If the annotations are present, the Webhook assigns the **Keptn Scheduler** to the Pod.
 This ensures that the Keptn Scheduler only gets Pods that have been annotated for it.
 A Pod `test-pod` modified by the Mutating Webhook looks as follows:

docs/content/en/docs/architecture/keptn-apps.md

@@ -64,12 +64,12 @@ plus specific tasks and evaluations that you define
 for the `KeptnApp` resource itself:
 
 * The annotations described in
-  [Basic annotations](../implementing/integrate/#basic-annotations)
+  [Basic annotations](../implementing/integrate.md#basic-annotations)
   are used to automatically generate `KeptnApp` resources
   that contain the identifications required
   to run the Keptn observability features.
 * You must manually add the annotations described in
-  [Pre- and post-deployment checks](../implementing/integrate/#pre--and-post-deployment-checks)
+  [Pre- and post-deployment checks](../implementing/integrate.md#pre--and-post-deployment-checks)
   to the basic `KeptnApp` manifest to define
   the evaluations and tasks you want to run pre- and post-deployment.
 
@@ -91,7 +91,7 @@ resource.
 
 ## How basic annotations are implemented
 
-The [Basic annotations](../implementing/integrate/#basic-annotations)
+The [Basic annotations](../implementing/integrate.md#basic-annotations)
 page gives instructions for applying the annotations or labels
 that identify the pods that Keptn should manage.
 

docs/content/en/docs/getting-started/lifecycle-management.md

@@ -23,7 +23,7 @@ When Keptn is successfully monitoring your deployments, it can also run arbitrar
 - post-deployment (after the post is scheduled)
 
 > Pre and post deployments can also run on a KeptnApp level.
-> See [annotations to KeptnApp](../implementing/integrate/_index.md#annotations-to-keptnapp)
+> See [annotations to KeptnApp](../implementing/integrate.md#annotations-to-keptnapp)
 
 ## Prerequisites: Deploy webhook sink
 
@@ -219,7 +219,7 @@ Do this by using the `keptn.sh/pre-deployment-tasks` label.
 ## Further Information
 
 There is a lot more you can do with KeptnTasks.
-See [pre and post deployment checks page](../implementing/integrate#pre--and-post-deployment-checks) to find out more.
+See [pre and post deployment checks page](../implementing/integrate.md#pre--and-post-deployment-checks) to find out more.
 
 ## What's next?
 

docs/content/en/docs/getting-started/observability.md

@@ -525,7 +525,7 @@ spec:
     that failed to deploy, perhaps because a
     `preDeploymentEvaluation` or `preDeploymentTask` failed.
     See
-    [Restart an Application Deployment](../implementing/restart-application-deployment/)
+    [Restart an Application Deployment](../implementing/restart-application-deployment.md)
     for a longer discussion of this.
   - **workloads**
     - **name** - name of this Kubernetes
@@ -595,4 +595,4 @@ See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information.
 
 Keptn can run pre and post deployment tasks and SLO evaluations automatically.
 
-Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks).
+Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks.md).

docs/content/en/docs/implementing/day-2-operations/_index.md → docs/content/en/docs/implementing/day-2-operations.md

@@ -5,19 +5,19 @@ weight: 500
 ---
 
 After you have successfully rolled out your application by following
-the instructions in the [integration guide](../integrate),
+the instructions in the [integration guide](./integrate.md),
 Keptn also assists you with day 2 operations for your application.
 
 Tasks that fall under this category include:
 
 * Updating the version of one or more [workloads](https://kubernetes.io/docs/concepts/workloads/)
 that are part of the same application
 * Adding a new [workload](https://kubernetes.io/docs/concepts/workloads/) to an existing application
-* Monitoring the health of your application using `KeptnMetrics`, as described [here](../evaluatemetrics.md)
+* Monitoring the health of your application using `KeptnMetrics`, as described [here](./evaluatemetrics.md)
 * Optimizing the resource usage of your applications by integrating
 `KeptnMetrics` into a
 [HorizontalPodAutoscaler (HPA)](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/),
-as described [here](../evaluatemetrics.md/#using-the-horizontalpodautoscaler)
+as described [here](./evaluatemetrics.md/#using-the-horizontalpodautoscaler)
 
 ## Updating Workload Versions
 
@@ -46,7 +46,7 @@ let's assume the following example, including
 a [workload](https://kubernetes.io/docs/concepts/workloads/) called `podtato-head-frontend` that includes a pre-task and
 a pre-evaluation.
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/deployment-initial.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/deployment-initial.yaml" >}}
 
 Now, let's assume that the configuration of that [workload](https://kubernetes.io/docs/concepts/workloads/) needs to be changed.
 In this example we assume that the image of that [workload](https://kubernetes.io/docs/concepts/workloads/)
@@ -59,7 +59,7 @@ of the result of any task or evaluation, e.g., when the previously used image ha
 and the image must be updated as quickly as possible.
 To do that, change `podtato-head-frontend` as follows:
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/deployment-new-image.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/deployment-new-image.yaml" >}}
 
 * **Update the configuration *and* the version label:**
 Doing so causes the `KeptnWorkload` that is associated
@@ -68,7 +68,7 @@ and therefore the pre-task `my-task` and pre-evaluation `my-evaluation`
 are executed before the updated pods are scheduled.
 In this case, the deployment should be changed as follows:
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/deployment-new-image-and-version.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/deployment-new-image-and-version.yaml" >}}
 
 If you have defined the related `KeptnApp` resource yourself,
 this must also be updated to refer to the updated `KeptnWorkload`.
@@ -77,14 +77,14 @@ this updated deployment is not able to progress otherwise.
 Therefore, make sure that the version of `podtato-head-frontend`
 is updated accordingly:
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/app-updated-version.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/app-updated-version.yaml" >}}
 
 Updating the `KeptnApp` also causes all pre-/post-tasks/evaluations
 of the `KeptnApp` to be executed again.
 In this example, this means that the tasks `wait-for-prometheus`,
 and `post-deployment-loadtests` will run again.
 
-If you are using the [automatic app discovery](../integrate#use-keptn-automatic-app-discovery),
+If you are using the [automatic app discovery](./integrate.md#use-keptn-automatic-app-discovery),
 you do not need to update the `KeptnApp` resource.
 Keptn will take care of that for you.
 
@@ -133,7 +133,7 @@ For example, to add the deployment `podtato-head-left-leg` to the
 `podtato-head` application, the configuration for that new deployment
 would look like this, with the required label being set:
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/new-deployment.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/new-deployment.yaml" >}}
 
 The `KeptnApp`, if defined by the user, should contain the
 reference to the newly added [workload](https://kubernetes.io/docs/concepts/workloads/).
@@ -142,7 +142,7 @@ progress if it is not part of a `KeptnApp`.
 For automatically discovered apps this is done
 automatically.
 
-{{< embed path="/docs/content/en/docs/implementing/day-2-operations/assets/app-with-new-workload.yaml" >}}
+{{< docsembed path="content/en/docs/implementing/assets/app-with-new-workload.yaml" >}}
 
 After applying the updated manifests, you can monitor the status
 of the application and related [workloads](https://kubernetes.io/docs/concepts/workloads/) using the following commands:

docs/content/en/docs/implementing/dora/_index.md → docs/content/en/docs/implementing/dora.md

@@ -21,7 +21,7 @@ DORA metrics provide information such as:
 
 Keptn starts collecting these metrics
 as soon as you apply
-[basic annotations](../integrate/#basic-annotations)
+[basic annotations](./integrate.md#basic-annotations)
 to the
 [Workload](https://kubernetes.io/docs/concepts/workloads/)
 resources
@@ -59,4 +59,4 @@ DORA metrics are also displayed on Grafana
 or whatever dashboard application you choose.
 For example:
 
-![DORA metrics](assets/dynatrace_dora_dashboard.png)
+![DORA metrics](../assets/dynatrace_dora_dashboard.png)

docs/content/en/docs/implementing/evaluatemetrics.md

@@ -56,7 +56,7 @@ To configure a data provider into your Keptn cluster:
 
 1. Create a secret if your data provider uses one.
    See
-   [Create secret text](../implementing/tasks/#create-secret-text).
+   [Create secret text](./tasks.md#create-secret-text).
 1. Install and configure each instance of each data provider
    into your Keptn cluster,
    following the instructions provided by the data source provider.

docs/content/en/docs/implementing/evaluations.md

@@ -44,7 +44,7 @@ you must:
   pre- and post-deployment evaluations for the `KeptnApp` itself.
 
 See
-[Pre- and post-deployment checks](../implementing/integrate/#pre--and-post-deployment-checks)
+[Pre- and post-deployment checks](./integrate.md#pre--and-post-deployment-checks)
 for details.
 
 Note the following: