feat: rewrite the continuous integration docs

Author: gforcada

docs/contributing/core/continuous-integration.md

@@ -9,103 +9,55 @@ myst:
 
 # 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.
+As a complex system build out of hundreds of small packages, Plone can be easily broken, inadvertently, with any change on any of its packages.
 
-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:
+For that a mix of a {term}`CI` system at [jenkins.plone.org](https://jenkins.plone.org) and GitHub Actions ensure that any change is thoroughly checked.
 
+Even better, if we allow to test a given set of changes **before** integrating them, we can be much more confident, that our changes will not break.
 
-## 1) Don't check in on a broken build
+That's exactly what we do at Plone, here is how:
 
-Do not make things more complicated for the developer who is responsible for breaking the build.
+## Pull requests
 
-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.
+An essential, and basic, point for all that is explained here to work is that we **do not commit to the main branch directly**.
 
-If the build is broken over a longer period of time (more than a couple of hours) you should either:
+Fortunately, GitHub, GitLab, and other source forgeries, have popularized the idea of pull/merge requests: rather than pushing your changes on the main branch, you push them to a separate branch.
 
--   notify the developer who is responsible for the breakage
--   fix the problem yourself
--   revert the commit so you and others can continue to work
+This apparently simple change has plenty of postive effects:
 
-```{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.
+- code can be shared without the fear of breaking anything
+- changes can be reviewed and improved by peer developers
+- automated checks can be performed
+- external integrations can run and provide reports
 
+## GitHub Actions
 
-## 4) Never go home on a broken build
+The first quick feedback one gets when creating a pull request is the automated GitHub Actions configured on that repository.
 
-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.
+They can range from security checks (is the committer allowed to commit on this repository?) to full automation pipelines (create a docker image and automatically deploy it on a test server).
 
+When it comes to continuous integration, GitHub Actions provides a first front line to ensure that the changes on the package itself remain valid: not only that tests do pass, but also that all quality checks configured are upheld.
 
-## 5) Always be prepared to revert to the previous revision
+## Jenkins
 
-For other developers to work on the build, you should always be prepared to revert to the previous passing revision.
+What GitHub Actions is for a single package, jenkins.plone.org is for the complete Plone packages.
 
+It not only tests changes to be made, but also pull requests pending to be merged.
 
-## 6) Time-box fixing before reverting
+Even better, when a set of changes span across multiple repositories, jenkins.plone.org still can test the combination of all the pull requests together.
 
-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.
+### As simple as a comment
 
+For the usual use case of testing a single pull request, a special crafted comment on the pull request itself is the only step that you need to do to get jenkins to run the tests against your changes.
 
-## 7) Don't comment out failing tests
+The special crafted comment is no secret, rather the other way around, the `mister-roboto` GitHub user greets you every time you create a new pull requests and reminding you of how to trigger jenkins:
 
-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.
+```text
+@jenkins-plone-org please run jobs
+```
 
+With that comment on a pull request, jenkins will set up a matrix of jobs to ensure that your changes work across any Plone versions and python versions that we currently support.
 
-## Further reading
+### mr.roboto
 
-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.
+The link between Jenkins and GitHub is encoded in mr.roboto, a service that is hooked into all Plone repositories and reacts at any change in them.