plone · stevepiercy · Jul 20, 2024 · Jun 19, 2024 · Jun 19, 2024 · Jun 19, 2024
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -18,7 +18,7 @@ build:
     # If there are no changes (git diff exits with 0) we force the command to return with 183.
     # This is a special exit code on Read the Docs that will cancel the build immediately.
     - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt;
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt;
       then
         exit 183;
       fi

diff --git a/coredev/agreement.md b/coredev/agreement.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Contributing, Plone"
 ---
 
+```{todo}
+All this can go, it's redundant
+```
+
 (contributing-to-plone-label)=
 
 # Contributing to Plone

diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Plone, continuous integration, best practices"
 ---
 
+```{todo}
+needs redaction and upgrade
+```
+
 # Essential continuous integration practices
 
 The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code.

diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md
@@ -8,8 +8,7 @@ myst:
 ---
 
 ```{todo}
-All this content should be audited against the plone.org site, probably removed, and replaced with a link to the authorative content on plone.org.
-Duplicating content is a maintenance burden.
+All this can go, it's redundant
 ```
 
 # Contributor's Agreement for Plone explained

diff --git a/coredev/culture.md b/coredev/culture.md
@@ -8,7 +8,7 @@ myst:
 ---
 
 ```{todo}
-This content is probably redundant and should be purged.
+All this can go, it's redundant
 ```
 
 # Plone developer culture

diff --git a/coredev/documentation.md b/coredev/documentation.md
@@ -6,6 +6,9 @@ myst:
     "property=og:title": "Writing documentation of Plone"
     "keywords": "documentation, Plone"
 ---
+```{todo}
+shorten & update
+```
 
 # Writing documentation
 

diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Plone, development"
 ---
 
+```{todo}
+Needs updating to Plone6, but contains useful info
+```
+
 # Getting started with development
 
 This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process.

diff --git a/coredev/git.md b/coredev/git.md
@@ -8,9 +8,7 @@ myst:
 ---
 
 ```{todo}
-I seriously question the value of this entire guide.
-I think it should be purged.
-Plone should not be in the business of teaching how to use git or GitHub.
+All this can go, it's redundant
 ```
 
 # Working with Git and GitHub

diff --git a/coredev/guidelines.md b/coredev/guidelines.md
@@ -7,9 +7,9 @@ myst:
     "keywords": ""
 ---
 
-```todo
-This should probably be purged.
-It is redundant to the default [CONTRUBITING.md](https://github.com/plone/.github/blob/main/CONTRIBUTING.md) and other files.
+```{todo}
+All this can go, it's redundant.
+IMPORTANT: it does need a rewrite on 6.docs.plone.org as there are many packages in the wild that link to it.
 ```
 
 % Note: this page is linked to from CONTRIBUTING.rst in all packages.  Keep it short!

diff --git a/coredev/index.md b/coredev/index.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Developing, Plone, Contributing"
 ---
 
+```{todo}
+Most of this can go
+```
+
 # Development in Plone
 
 This part describes the process of development in Plone.

diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "mr.developer"
 ---
 
+```{todo}
+Review, but keep
+```
+
 # `mr.developer`
 
 This buildout uses `mr.developer` to manage package development.

diff --git a/coredev/packages-dependencies.md b/coredev/packages-dependencies.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Architecture, packages, dependecies, Plone"
 ---
 
+```{todo}
+Needs grammar/style check, and re-do the ASCII art as Mermaid diagram for added clarity and visuals
+```
+
 # Architecture: packages and dependecies
 
 This chapter describes the architecture of Plone's packages and dependencies.

diff --git a/coredev/plip-review.md b/coredev/plip-review.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "PLIP, review, Plone Improvement Proposal, Plone"
 ---
 
+```{todo}
+Combine with PLIP page, remove obsolete technologies, go over language
+```
+
 # PLIP review
 
 A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone.

diff --git a/coredev/plips.md b/coredev/plips.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Plone Improvement Proposal, PLIP)"
 ---
 
+```{todo}
+Needs language review
+```
+
 # Plone Improvement Proposals (PLIPs)
 
 A PLIP is a Plone Improvement Proposal.

diff --git a/coredev/release.md b/coredev/release.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Plone, release, process"
 ---
 
+```{todo}
+Can stay, as it needs a place to live. Check in with Release Managers to update content, if needed
+```
+
 # Plone release process
 
 This chapter describes the process to release Plone and its packages.

diff --git a/coredev/roboto.md b/coredev/roboto.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Mr. Roboto, mr.roboto, Plone"
 ---
 
+```{todo}
+Needs content review, it looks highly outdated with references to CVS, kgs and other obsolete tech
+```
+
 # Mr. Roboto
 
 ```{todo}
@@ -26,7 +30,7 @@ When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze
 
 ```{todo}
 `http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found.
-``` 
+```
 
 
 ## Job finishes

diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md
@@ -7,6 +7,10 @@ myst:
     "keywords": "Troubleshooting, development issues, Plone"
 ---
 
+```{todo}
+Needs review. In general, a 'troubleshooting' page is nice, but this looks outdated
+```
+
 # Troubleshooting
 
 This chapter describes how to troubleshoot development issues in Plone.

diff --git a/docs/conf.py b/docs/conf.py
@@ -59,6 +59,7 @@
     "sphinx.ext.viewcode",  # plone.api
     "sphinx.ext.autosummary",  # plone.api
     "sphinx.ext.graphviz",
+    "sphinxcontrib.mermaid",
     "notfound.extension",
 ]
 
@@ -99,6 +100,8 @@
     r"https://stackoverflow.com",  # volto and documentation  # TODO retest with latest Sphinx.
     r"https://web.archive.org/",  # volto
     r"https://www.youtube.com/playlist",  # volto, TODO remove after installing sphinxcontrib.youtube
+    r"https://www.upc.edu/en",  # TODO remove after their certificate is fixed
+    r"http://z3c.pt",  # fluke where Sphinx interprets this as a URL
 ]
 linkcheck_anchors = True
 linkcheck_timeout = 5
@@ -179,6 +182,8 @@
     "fawrench": '<span class="fa fa-wrench" style="font-size: 1.6em;"></span>',
 }
 
+mermaid_version = "10.9.1"
+
 # -- Intersphinx configuration ----------------------------------
 
 # This extension can generate automatic links to the documentation of objects
@@ -197,6 +202,7 @@
 # the entire Plone Documentation is built.
 intersphinx_mapping = {
     "plone": ("https://6.docs.plone.org/", None),  # for imported packages
+    "plone5": ("https://5.docs.plone.org/", None),
     "python": ("https://docs.python.org/3/", None),
     "training": ("https://training.plone.org/", None),
     "training-2022": ("https://2022.training.plone.org/", None),
@@ -329,6 +335,7 @@
     "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github",
 }
 
+
 # An extension that allows replacements for code blocks that
 # are not supported in `rst_epilog` or other substitutions.
 # https://stackoverflow.com/a/56328457/2214933

diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md
@@ -0,0 +1,111 @@
+---
+myst:
+  html_meta:
+    "description": "Essential continuous integration practices"
+    "property=og:description": "Essential continuous integration practices"
+    "property=og:title": "Essential continuous integration practices"
+    "keywords": "Plone, continuous integration, best practices"
+---
+
+# Essential continuous integration practices
+
+The {term}`CI` system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code.
+
+Build breakages are a normal and expected part of the development process.
+The aim is to find errors and remove them as quickly as possible, without expecting perfection and zero errors.
+However, there are some essential practices that you need follow to achieve a stable build:
+
+
+## 1) Don't check in on a broken build
+
+Do not make things more complicated for the developer who is responsible for breaking the build.
+
+If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it.
+This strategy gives the developer the best option to find out what caused the breakage and fix it immediately.
+Fixing the build is easier with a clear look at the problem.
+Checking in further changes and triggering new builds will complicate matters and lead to more problems.
+
+If the build is broken over a longer period of time (more than a couple of hours) you should either:
+
+-   notify the developer who is responsible for the breakage
+-   fix the problem yourself
+-   revert the commit so you and others can continue to work
+
+```{note}
+There is one exception to this rule.
+Sometimes there are changes or tests that depend on changes in other packages.
+If this is the case, there is no way around breaking a single build for a certain period of time.
+In this case, run the all tests locally with all the changes and commit them within a time frame of ten minutes.
+```
+
+
+## 2) Always run all commit tests locally before committing
+
+Follow this practice so the build stays green, and other developers can continue to work without breaking the first rule.
+
+Remember that Plone development can happen all over the world, at all times.
+Other developers may have checked in changes since your last synchronization.
+These may interact with your work.
+
+Therefore it's essential that you merge changes from the main branch into your feature branch, then run the tests again, before you push your changes to GitHub.
+
+A common source of errors on check-in is to forget to add some files to the repository.
+Use {command}`git status` to check and correct for this.
+Also double-check to not check in files that should not be part of a package, such as editor configuration files and git submodules.
+
+
+## 3) Wait for commit tests to pass before moving on
+
+Always monitor the build's progress, and fix the problem right away if it fails.
+If you introduced a regression, you have a far better chance of fixing the build sooner than later.
+Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for you.
+
+
+## 4) Never go home on a broken build
+
+Take into account the first rule of CI ("Don't check in on a broken build").
+Breaking the build essentially stops all other developers from working on it.
+Therefore going home on a broken build—or even on a build that has not finished yet—is _not_ acceptable.
+It will prevent all other developers from working, or they will need to fix the errors that you introduced.
+
+
+## 5) Always be prepared to revert to the previous revision
+
+For other developers to work on the build, you should always be prepared to revert to the previous passing revision.
+
+
+## 6) Time-box fixing before reverting
+
+When the build breaks on check-in, try to fix it for ten minutes.
+If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system.
+This way you will allow other developers to continue to work.
+
+
+## 7) Don't comment out failing tests
+
+Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quickly as possible.
+While this impulse is understandable, it is _not acceptable_.
+
+The tests were passing for a while and then start to fail.
+This means that you either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason.
+
+You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists).
+
+
+## 8) Take responsibility for all breakages that result from your changes
+
+If you commit a change and all the tests you wrote pass, but others break, the build is still broken.
+This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on.
+This means that you have introduced a regression bug into the application.
+
+It is _your responsibility_ to fix all tests that do not pass because of your changes.
+
+There are some tests in Plone that fail randomly, and the community is always working on fixing those.
+If you think you hit such a test, try to fix it or re-run the Jenkins job to see if it passes again.
+
+In any case, the developer who made the commit is responsible to make it pass.
+
+
+## Further reading
+
+These rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community.