From 2d5b09449404ff6ee9fd15c4af1d013e688ecbde Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 4 Oct 2023 06:00:58 -0700 Subject: [PATCH 1/7] docs: move publishing info to contribute guide Signed-off-by: Meg McRoberts --- docs/CONTRIBUTING.md | 93 +------------------ .../en/contribute/docs/publish/_index.md | 71 ++++++++++++++ .../components/scheduler/_index.md | 2 +- 3 files changed, 74 insertions(+), 92 deletions(-) create mode 100644 docs/content/en/contribute/docs/publish/_index.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9fce62367d..5846021c69 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -37,74 +37,6 @@ The documentation source is stored on github.com and you use the standard github facilities to modify it. Please check [Working with Git](content/en/contribute/general/git/_index.md). -## Choosing the correct branch when contributing - -New writing goes to the `main` branch and can be viewed on the Releases -> development dropdown menu. -We have staging and production levels for our documentation which are as follows: - -* **Latest:** official documentation of the current Keptn release - * [link](https://lifecycle.keptn.sh): - This is the build of the `page` branch. - -* **Development:** documentation being staged for the next Keptn release - * [link](https://main.lifecycle.keptn.sh): - This is the latest build of the `main` branch. - -* **Previous versions:** documentation for earlier releases. - These are listed at [link](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). - -* **Contribute:** current version of the "Contribute" guide - that is available from a tab on the documentation site. - -Let's take a look what happens when your changes are merged in `main` and `page` branch respectively. - -## Latest -- Official documentation (Production) - -This set of documentation pertains to the latest KLT release and resides within an -isolated branch known as `page`. -When a new version of KLT is launched, the contents of the `development` -branch are rolled into this branch. -Additionally, it's important to recognize that any -document changes made using the "Edit this page" feature are seamlessly integrated into this branch. - -This uses the `latest` label so that links to a doc page -remain valid across software and documentation updates. - -* build: on each push to `page` with documentation changes -* build-environment: production -* config folder: [production](./config/production/) - -A new version is generated when we push the `main` branch to production to release a new version of the docs page. -This means, that the content of the old version on the `page` branch will be copied over -to a `docs-` folder and the new version will be pushed into the `docs` folder. -This way, no changes or older versions get overwritten. - -## Development documentation (Staging) - -This page contains the documentation being staged for the next Keptn release. -It contains information about new and changed features and functionality -as well as general documentation improvements. -It is built regularly and can be easily accessed from the `Releases` tab on the documentation site. - -* build: on each push to `main` with documentation changes - from a user's local branch, from the github editor, or from codespaces -* build-environment: main -* config folder: [main](./config/staging/) - -This version represents the pre-release iteration of the documentation for the upcoming Keptn release. -Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch. - -When a new Keptn version is officially launched, this branch is elevated to the status of `latest`. -In exceptional cases, a pull request that includes vital documentation enhancements may be discreetly -advanced to `latest` without the need for a software release. - -## Previous Versions - -Keptn documentation is versioned. -By default, the version for the current Keptn release -is displayed on the documentation page but users can select other versions from the Releases tab. -The previous versions of the Keptn Documentation are available [here](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). - ### Developer Certification of Origin (DCO) All commits must be accompanied by a DCO sign-off. @@ -116,27 +48,6 @@ for more information. Please check [Source File Structure](content/en/contribute/docs/source-file-structure/_index.md).. -## Guidelines for working on documentation in development versus already released documentation - -[This material will be provided when we define the versioning scheme to use] - -### Documentation for new features - -Most documentation changes should be made to the docs-dev branch, -which means creating a PR in the `lifecycle-toolkit` repository -under the `docs/content/en/docs` directory. -You can view the local build as described above. -We are releasing new versions of the software frequently -so this makes new content available reasonably quickly. - -### Documentation for published docs - -If a critical problem needs to be solved immediately, -you can modify the documentation source in the sandbox. -In this case, modify the files in the -`keptn-sandbox/lifecycle-toolkit-docs` repository directly. -You can view these changes locally on the `localhost:1314` port. +## Location of published docs -Note that changes made to the docs in the sandbox -will be overwritten so the same changes should be applied -to the corresponding doc source in the `lifecycle-toolkit` documentation. +Please check [Published doc structure-](content/en/contribute/docs/publish/_index.md). diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md new file mode 100644 index 0000000000..09c45a28b6 --- /dev/null +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -0,0 +1,71 @@ +--- +title: Published Doc Structure +description: Structure of the published documentation +weight: 450 +--- + +New writing goes to the `main` branch and can be viewed on the Releases -> development dropdown menu. +We have staging and production levels for our documentation which are as follows: + +* **Latest:** official documentation of the current Keptn release + * [link](https://lifecycle.keptn.sh): + This is the build of the `page` branch. + +* **Development:** documentation being staged for the next Keptn release + * [link](https://main.lifecycle.keptn.sh): + This is the latest build of the `main` branch. + +* **Previous versions:** documentation for earlier releases. + These are listed at [link](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). + +* **Contribute:** current version of the "Contribute" guide + that is available from a tab on the documentation site. + +Let's take a look what happens when your changes are merged in `main` and `page` branch respectively. + +## Latest -- Official documentation (Production) + +This set of documentation pertains to the latest KLT release and resides within an +isolated branch known as `page`. +When a new version of KLT is launched, the contents of the `development` +branch are rolled into this branch. +Additionally, it's important to recognize that any +document changes made using the "Edit this page" feature are seamlessly integrated into this branch. + +This uses the `latest` label so that links to a doc page +remain valid across software and documentation updates. + +* build: on each push to `page` with documentation changes +* build-environment: production +* config folder: [production](./config/production/) + +A new version is generated when we push the `main` branch to production to release a new version of the docs page. +This means, that the content of the old version on the `page` branch will be copied over +to a `docs-` folder and the new version will be pushed into the `docs` folder. +This way, no changes or older versions get overwritten. + +## Development documentation (Staging) + +This page contains the documentation being staged for the next Keptn release. +It contains information about new and changed features and functionality +as well as general documentation improvements. +It is built regularly and can be easily accessed from the `Releases` tab on the documentation site. + +* build: on each push to `main` with documentation changes + from a user's local branch, from the github editor, or from codespaces +* build-environment: main +* config folder: [main](./config/staging/) + +This version represents the pre-release iteration of the documentation for the upcoming Keptn release. +Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch. + +When a new Keptn version is officially launched, this branch is elevated to the status of `latest`. +In exceptional cases, a pull request that includes vital documentation enhancements may be discreetly +advanced to `latest` without the need for a software release. + +## Previous Versions + +Keptn documentation is versioned. +By default, the version for the current Keptn release +is displayed on the documentation page but users can select other versions from the Releases tab. +The previous versions of the Keptn Documentation are available [here](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). diff --git a/docs/content/en/docs/architecture/components/scheduler/_index.md b/docs/content/en/docs/architecture/components/scheduler/_index.md index 73a36ac887..6d696704a7 100644 --- a/docs/content/en/docs/architecture/components/scheduler/_index.md +++ b/docs/content/en/docs/architecture/components/scheduler/_index.md @@ -15,7 +15,7 @@ and orchestrate the deployment process. If the Keptn helm chart value `schedulingGatesEnabled` is set to `true`, and Keptn is running on a Kubernetes version greater than 1.26, Keptn does not install a scheduler plugin. Instead, it uses -the [Pod Scheduling Readiness K8s API](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness) +the [Pod Scheduling Readiness K8s API](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness) to gate Pods until the required deployment checks pass. ## Keptn Scheduling Gates for K8s 1.27 and above From a966de11f93ff516d0551ebd00c3cf92445d62cb Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 10 Oct 2023 15:05:17 -0700 Subject: [PATCH 2/7] Update docs/content/en/contribute/docs/publish/_index.md Signed-off-by: Meg McRoberts meg.mcroberts@dynatrace.com Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Meg McRoberts --- docs/content/en/contribute/docs/publish/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md index 09c45a28b6..35fde36359 100644 --- a/docs/content/en/contribute/docs/publish/_index.md +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -27,7 +27,7 @@ Let's take a look what happens when your changes are merged in `main` and `page` This set of documentation pertains to the latest KLT release and resides within an isolated branch known as `page`. -When a new version of KLT is launched, the contents of the `development` +When a new version of Keptn is launched, the contents of the `development` branch are rolled into this branch. Additionally, it's important to recognize that any document changes made using the "Edit this page" feature are seamlessly integrated into this branch. From 22c556dc5f8169b2c367343cfe53d9140f55cfa3 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 10 Oct 2023 15:06:05 -0700 Subject: [PATCH 3/7] Update docs/CONTRIBUTING.md Signed-off-by: Meg McRoberts meg.mcroberts@dynatrace.com Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Meg McRoberts --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5846021c69..3757173a37 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -50,4 +50,4 @@ Please check [Source File Structure](content/en/contribute/docs/source-file-stru ## Location of published docs -Please check [Published doc structure-](content/en/contribute/docs/publish/_index.md). +Please check [Published doc structure](content/en/contribute/docs/publish/_index.md). From 30ca1d8af8e7117600b8f6eae75fb8f14193c9e9 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 10 Oct 2023 15:08:56 -0700 Subject: [PATCH 4/7] Update docs/content/en/contribute/docs/publish/_index.md Signed-off-by: Meg McRoberts meg.mcroberts@dynatrace.com Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Meg McRoberts --- docs/content/en/contribute/docs/publish/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md index 35fde36359..5fbda4dd30 100644 --- a/docs/content/en/contribute/docs/publish/_index.md +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -25,7 +25,7 @@ Let's take a look what happens when your changes are merged in `main` and `page` ## Latest -- Official documentation (Production) -This set of documentation pertains to the latest KLT release and resides within an +This set of documentation pertains to the latest Keptn release and resides within an isolated branch known as `page`. When a new version of Keptn is launched, the contents of the `development` branch are rolled into this branch. From 892e719239bb114c2715dcb9161be32cd2fd7c43 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 10 Oct 2023 20:08:05 -0700 Subject: [PATCH 5/7] tried to fix bad xrefs Signed-off-by: Meg McRoberts --- docs/content/en/contribute/docs/publish/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md index 5fbda4dd30..91821338eb 100644 --- a/docs/content/en/contribute/docs/publish/_index.md +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -37,7 +37,7 @@ remain valid across software and documentation updates. * build: on each push to `page` with documentation changes * build-environment: production -* config folder: [production](./config/production/) +* config folder: [production](../../../../../config/production) A new version is generated when we push the `main` branch to production to release a new version of the docs page. This means, that the content of the old version on the `page` branch will be copied over @@ -54,7 +54,7 @@ It is built regularly and can be easily accessed from the `Releases` tab on the * build: on each push to `main` with documentation changes from a user's local branch, from the github editor, or from codespaces * build-environment: main -* config folder: [main](./config/staging/) +* config folder: [main](../../../../../config/staging/) This version represents the pre-release iteration of the documentation for the upcoming Keptn release. Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch. From ad9e46ae56a3c90410bf9a08ccb9bebccc3cfc26 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Sun, 15 Oct 2023 18:48:24 -0700 Subject: [PATCH 6/7] tried to fix links to config directories Signed-off-by: Meg McRoberts --- docs/content/en/contribute/docs/publish/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md index 91821338eb..d1009d6d15 100644 --- a/docs/content/en/contribute/docs/publish/_index.md +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -37,7 +37,7 @@ remain valid across software and documentation updates. * build: on each push to `page` with documentation changes * build-environment: production -* config folder: [production](../../../../../config/production) +* config folder: [production](https://github.com/keptn/lifecycle-toolkit/docs/config/production) A new version is generated when we push the `main` branch to production to release a new version of the docs page. This means, that the content of the old version on the `page` branch will be copied over @@ -54,7 +54,7 @@ It is built regularly and can be easily accessed from the `Releases` tab on the * build: on each push to `main` with documentation changes from a user's local branch, from the github editor, or from codespaces * build-environment: main -* config folder: [main](../../../../../config/staging/) +* config folder: [staging](https://github.com/keptn/lifecycle-toolkit/docs/config/staging) This version represents the pre-release iteration of the documentation for the upcoming Keptn release. Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch. From bf41eb4feb593cbe832b618c7f7f23e20ccd08f0 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 17 Oct 2023 03:25:38 -0700 Subject: [PATCH 7/7] xrefs to doc/config directory Signed-off-by: Meg McRoberts --- docs/content/en/contribute/docs/publish/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/contribute/docs/publish/_index.md b/docs/content/en/contribute/docs/publish/_index.md index d1009d6d15..3ffb8b9ee8 100644 --- a/docs/content/en/contribute/docs/publish/_index.md +++ b/docs/content/en/contribute/docs/publish/_index.md @@ -37,7 +37,7 @@ remain valid across software and documentation updates. * build: on each push to `page` with documentation changes * build-environment: production -* config folder: [production](https://github.com/keptn/lifecycle-toolkit/docs/config/production) +* config folder: [production](https://github.com/keptn/lifecycle-toolkit/tree/main/docs/config/production) A new version is generated when we push the `main` branch to production to release a new version of the docs page. This means, that the content of the old version on the `page` branch will be copied over @@ -54,7 +54,7 @@ It is built regularly and can be easily accessed from the `Releases` tab on the * build: on each push to `main` with documentation changes from a user's local branch, from the github editor, or from codespaces * build-environment: main -* config folder: [staging](https://github.com/keptn/lifecycle-toolkit/docs/config/staging) +* config folder: [staging](https://github.com/keptn/lifecycle-toolkit/tree/main/docs/config/staging) This version represents the pre-release iteration of the documentation for the upcoming Keptn release. Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch.