From 38c7ac89cb3d9018740a72e5c00b83ed52990628 Mon Sep 17 00:00:00 2001 From: vibhu gupta Date: Fri, 21 Nov 2025 13:05:52 +0530 Subject: [PATCH 1/3] Improve DevOps documentation section and formatting --- .../cookieplone-make-commands.md | 61 ++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index 22b3c1e18..c174fd969 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -160,4 +160,63 @@ You can run the following make targets by using the command structure of `make < `build-images` : Invokes the target `build-image` in both `backend/Makefile` and `frontend/Makefile`. - This builds Docker images for both backend and frontend. \ No newline at end of file + This builds Docker images for both backend and frontend. + + +## Devops + +Cookieplone projects can optionally include a `devops` folder when deployment-related options are selected during project generation, such as: + +- **Add Ansible playbooks?** +- **Add GitHub Action to Deploy this project?** + +When these options are enabled, Cookieplone generates a `devops/Makefile` containing deployment and CI/CD helper commands. + +You can view the available DevOps commands in your generated project by running: + +```bash +# from the project root +make -C devops help + +# or +cd devops +make help + +``` +The commands vary depending on your Cookieplone template options, so this is the authoritative way to inspect your environment. + +Below is the current working output of the DevOps make help command +(as fixed in cookieplone-templates#305): + +``` +# === DevOps Makefile Commands === +deploy Deploy the project using the configured provider +deploy-check Validate deployment configuration +deploy-ansible Run Ansible playbooks for provisioning +deploy-rollback Roll back the last deployment +deploy-status Show deployment status or active revision +secrets-edit Edit encrypted secrets +secrets-view View decrypted secrets +lint Lint Ansible and DevOps configuration files +format Format DevOps files (YAML, JSON, etc.) +clean Clean temporary deployment artifacts +help Show this help +``` +These commands support tasks such as: + +- provisioning via **Ansible** +- deploying through **GitHub Actions** or **GitLab CI** +- editing and viewing **encrypted secrets** +- linting DevOps configuration +- rolling back deployments + +## Additional Documentation + +The `devops` folder also includes README files generated by Cookieplone, which contain deployment instructions tailored to your setup: + +- {file}`devops/README.md` +- {file}`devops/README-GHA.md` (GitHub Actions deployment) +- {file}`devops/README-GITLAB.md` (GitLab deployment) + +These documents provide hands-on details such as provisioning steps, CI configuration, and environment requirements. +This reference section avoids duplicating that information and instead links to those files. \ No newline at end of file From c73ff544be3a624d7a0baae94b2846a1464c6f92 Mon Sep 17 00:00:00 2001 From: vibhu gupta Date: Sun, 23 Nov 2025 19:41:50 +0530 Subject: [PATCH 2/3] Apply maintainer review suggestions for DevOps documentation (Fixes #1988) --- .../cookieplone-make-commands.md | 46 ++++++++----------- 1 file changed, 18 insertions(+), 28 deletions(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index c174fd969..d2f542b5a 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -11,16 +11,7 @@ myst: This reference guide describes the function and purpose of all the `make` commands found in a {term}`Cookieplone` project. It's organized according to its components. -- Frontend -- Backend -- Documentation -- Environment -- Quality assurance (QA) -- Internationalization (i18n) -- Testing -- Container images -- Local stack -- Acceptance + ## Frontend @@ -165,12 +156,12 @@ You can run the following make targets by using the command structure of `make < ## Devops -Cookieplone projects can optionally include a `devops` folder when deployment-related options are selected during project generation, such as: - -- **Add Ansible playbooks?** -- **Add GitHub Action to Deploy this project?** +Cookieplone projects include a `devops` folder when deployment-related questions are answered "Yes" during project generation. +These questions include the following. +- Add Ansible playbooks? +- Add GitHub Action to Deploy this project? -When these options are enabled, Cookieplone generates a `devops/Makefile` containing deployment and CI/CD helper commands. +When any of these options are selected, Cookieplone generates a {file}`devops/Makefile` file containing deployment and CI/CD helper commands. You can view the available DevOps commands in your generated project by running: @@ -202,21 +193,20 @@ format Format DevOps files (YAML, JSON, etc.) clean Clean temporary deployment artifacts help Show this help ``` -These commands support tasks such as: +These commands support devops tasks, such as: +- provisioning via Ansible +- deploying through GitHub Actions or GitLab CI +- editing and viewing encrypted secrets +- linting devops configuration +- rolling back deployments -- provisioning via **Ansible** -- deploying through **GitHub Actions** or **GitLab CI** -- editing and viewing **encrypted secrets** -- linting DevOps configuration -- rolling back deployments -## Additional Documentation +## Additional documentation -The `devops` folder also includes README files generated by Cookieplone, which contain deployment instructions tailored to your setup: +The {file}`devops` folder also includes {file}`README*.md` files generated by Cookieplone, which contain deployment instructions tailored to your setup: -- {file}`devops/README.md` -- {file}`devops/README-GHA.md` (GitHub Actions deployment) -- {file}`devops/README-GITLAB.md` (GitLab deployment) +- {file}`devops/README.md` +- {file}`devops/README-GHA.md` for GitHub Actions deployment +- {file}`devops/README-GITLAB.md` for GitLab deployment -These documents provide hands-on details such as provisioning steps, CI configuration, and environment requirements. -This reference section avoids duplicating that information and instead links to those files. \ No newline at end of file +These documents provide details, such as provisioning steps, CI configuration, and environment requirements, and are the authoritative source of documentation for devops. \ No newline at end of file From 1bd3422535b216d94bb048607cbf0014632ea337 Mon Sep 17 00:00:00 2001 From: vibhu gupta Date: Mon, 24 Nov 2025 11:28:51 +0530 Subject: [PATCH 3/3] Apply maintainer review suggestions for DevOps documentation --- .../cookieplone-make-commands.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index d2f542b5a..ee2f98e7e 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -158,28 +158,30 @@ You can run the following make targets by using the command structure of `make < Cookieplone projects include a `devops` folder when deployment-related questions are answered "Yes" during project generation. These questions include the following. + - Add Ansible playbooks? - Add GitHub Action to Deploy this project? When any of these options are selected, Cookieplone generates a {file}`devops/Makefile` file containing deployment and CI/CD helper commands. -You can view the available DevOps commands in your generated project by running: +You can view the available devops commands in your generated project by running the following help command from the project root. -```bash -# from the project root +```shell make -C devops help +``` -# or +Alternatively, change the working directory to {file}`devops` and run its help command. + +```shell cd devops make help - ``` -The commands vary depending on your Cookieplone template options, so this is the authoritative way to inspect your environment. -Below is the current working output of the DevOps make help command -(as fixed in cookieplone-templates#305): +The available commands align with the selected Cookieplone template options. -``` +When all devops options have been selected, the following output is the result of running the devops help command. + +```console # === DevOps Makefile Commands === deploy Deploy the project using the configured provider deploy-check Validate deployment configuration @@ -193,7 +195,9 @@ format Format DevOps files (YAML, JSON, etc.) clean Clean temporary deployment artifacts help Show this help ``` + These commands support devops tasks, such as: + - provisioning via Ansible - deploying through GitHub Actions or GitLab CI - editing and viewing encrypted secrets