Document DevOps Make Commands on Cookieplone Reference Guide (Fixes #1988) #1989
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
|
@VibhuGupta-dev thanks for your contribution. However, please read and follow Contribute to documentation and Granting permission to publish. I can't merge this without your permission to publish in either of the two acceptable forms, and therefore I won't start a review until that's been resolved. Please let me know. Thank you! |
Contributor
Author
|
I, Vibhu Gupta, agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation. |
stevepiercy
requested changes
Nov 20, 2025
Contributor
stevepiercy
left a comment
stevepiercy
left a comment
There was a problem hiding this comment.
Thanks for working on this.
I found a couple of unrelated things that need to be addressed.
Otherwise my suggestions are intended for brevity, clarity, style guide, and other minor tweaks.
If you agree with numerous changes, you can use the "Add suggestion to batch" button in GitHub's UI to save time and avoid spamming with over a dozen notifications. Thank you!
Contributor
There was a problem hiding this comment.
Revert changes to this file. It has nothing to do with this PR.
Comment on lines
+209
to
+218
| (contentIcons)= | ||
| contentIcons | ||
| A Volto configuration option (typically a boolean) that controls whether small content-type icons are shown next to items in lists, teasers, and navigation components. | ||
| When enabled, an icon representing the item's content type (for example: document, image, file) is displayed alongside the item's title. | ||
| (excludeLinksAndReferencesMenuItem)= | ||
| excludeLinksAndReferencesMenuItem | ||
| A Volto configuration key or menu setting that, when enabled, removes or hides the "Links and References" menu item from link pickers or site menus. | ||
| Use this option to prevent the Links and References entry from appearing in UI menus where it is not desired. | ||
Contributor
There was a problem hiding this comment.
Suggested change
| (contentIcons)= | |
| contentIcons | |
| A Volto configuration option (typically a boolean) that controls whether small content-type icons are shown next to items in lists, teasers, and navigation components. | |
| When enabled, an icon representing the item's content type (for example: document, image, file) is displayed alongside the item's title. | |
| (excludeLinksAndReferencesMenuItem)= | |
| excludeLinksAndReferencesMenuItem | |
| A Volto configuration key or menu setting that, when enabled, removes or hides the "Links and References" menu item from link pickers or site menus. | |
| Use this option to prevent the Links and References entry from appearing in UI menus where it is not desired. |
Contributor
There was a problem hiding this comment.
Please delete lines 14-23. They're out of sync with the content and don't actually provide anything useful.
Comment on lines
+167
to
+170
| 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?** |
Contributor
There was a problem hiding this comment.
Suggested change
| 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? |
| - **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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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. |
Comment on lines
+204
to
+210
| 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 |
Contributor
There was a problem hiding this comment.
Don't overemphasize things. It's distracting.
Suggested change
| 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 | |
| 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 |
| - linting DevOps configuration | ||
| - rolling back deployments | ||
|
|
||
| ## Additional Documentation |
Contributor
There was a problem hiding this comment.
Sentence case headings.
Suggested change
| ## Additional Documentation | |
| ## Additional documentation |
|
|
||
| ## Additional Documentation | ||
|
|
||
| The `devops` folder also includes README files generated by Cookieplone, which contain deployment instructions tailored to your setup: |
Contributor
There was a problem hiding this comment.
Suggested change
| 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: |
Comment on lines
+216
to
+218
| - {file}`devops/README.md` | ||
| - {file}`devops/README-GHA.md` (GitHub Actions deployment) | ||
| - {file}`devops/README-GITLAB.md` (GitLab deployment) |
Contributor
There was a problem hiding this comment.
Suggested change
| - {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 |
Comment on lines
+220
to
+221
| 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. |
Contributor
There was a problem hiding this comment.
Let's combine this into one sentence. Also there are no links.
Suggested change
| 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. | |
| These documents provide details, such as provisioning steps, CI configuration, and environment requirements, and are the authoritative source of documentation for devops. |
github-project-automation
bot
moved this from New
to In Progress
in Plone Documentation
Contributor
|
Also we can't merge this until plone/cookieplone-templates#306 is merged. @davisagli @ericof |
github-project-automation
bot
moved this from In Progress
to Done
in Plone Documentation
This was referenced Nov 21, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Caution
DO NOT MERGE UNTIL plone/cookieplone-templates#306 IS MERGED!
Fixes #1988
This PR adds the missing DevOps documentation to the docs/reference-guide/cookieplone-make-commands.md page.
What was added:
Introduced a new DevOps section describing how Cookieplone generates the devops folder when deployment options are selected.
Added instructions on how to view DevOps Makefile commands using make -C devops help.
Added the full, corrected list of DevOps Makefile commands (based on cookieplone-templates#305).
Documented tasks supported by these commands, including deployment, Ansible provisioning, secret management, linting, and rollback.
Added references to the generated DevOps README files:
devops/README.md
devops/README-GHA.md
devops/README-GITLAB.md
Improved structure and formatting for consistency with the rest of the documentation.
This update closes the gap in the documentation where DevOps commands were previously missing.
📚 Documentation preview 📚: https://plone6--1989.org.readthedocs.build/