|
1 | 1 | --- |
2 | 2 | myst: |
3 | 3 | html_meta: |
4 | | - "description": "Essential continuous integration practices" |
5 | | - "property=og:description": "Essential continuous integration practices" |
6 | | - "property=og:title": "Essential continuous integration practices" |
7 | | - "keywords": "Plone, continuous integration, best practices" |
| 4 | + "description": "Working with continuous integration via Jenkins and GitHub workflows in Plone" |
| 5 | + "property=og:description": "Working with continuous integration via Jenkins and GitHub workflows in Plone" |
| 6 | + "property=og:title": "Continuous integration" |
| 7 | + "keywords": "Plone, continuous integration, Jenkins, GitHub workflows" |
8 | 8 | --- |
9 | 9 |
|
10 | | -# Essential continuous integration practices |
| 10 | +# Continuous integration |
11 | 11 |
|
12 | | -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. |
| 12 | +As a complex system built from hundreds of small packages, Plone can be easily and inadvertently broken from a change to any of its packages. |
| 13 | +To help prevent breaking Plone, a mix of a {term}`continuous integration` (CI) systems of GitHub workflows and Jenkins thoroughly checks all changes. |
13 | 14 |
|
14 | | -Build breakages are a normal and expected part of the development process. |
15 | | -The aim is to find errors and remove them as quickly as possible, without expecting perfection and zero errors. |
16 | | -However, there are some essential practices that you need follow to achieve a stable build: |
| 15 | +Do not use continuous integration as a replacement for running tests and other checks locally before pushing commits to a Plone repository. |
| 16 | +See {ref}`test-and-code-quality-label` for an explanation, and {ref}`contributing-specific-contribution-policies-for-projects-label` for a project's specific contributing guidelines. |
17 | 17 |
|
18 | 18 |
|
19 | | -## 1) Don't check in on a broken build |
| 19 | +## GitHub workflows |
20 | 20 |
|
21 | | -Do not make things more complicated for the developer who is responsible for breaking the build. |
| 21 | +Most Plone repositories use {term}`GitHub workflows` to run tests, check code quality, and perform other CI tasks on pushed commits to an open pull request. |
22 | 22 |
|
23 | | -If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it. |
24 | | -This strategy gives the developer the best option to find out what caused the breakage and fix it immediately. |
25 | | -Fixing the build is easier with a clear look at the problem. |
26 | | -Checking in further changes and triggering new builds will complicate matters and lead to more problems. |
| 23 | +If a pull request is opened from a branch in the repository, then checks will automatically run. |
| 24 | +Only members of certain Plone GitHub organization teams and users with write permission in the repository can do this. |
| 25 | +Otherwise GitHub workflows do not run automatically, and require a member with write permission to run the checks. |
27 | 26 |
|
28 | | -If the build is broken over a longer period of time (more than a couple of hours) you should either: |
| 27 | +GitHub workflows should pass before running Jenkins checks and before merging an open pull request. |
29 | 28 |
|
30 | | -- notify the developer who is responsible for the breakage |
31 | | -- fix the problem yourself |
32 | | -- revert the commit so you and others can continue to work |
33 | 29 |
|
34 | | -```{note} |
35 | | -There is one exception to this rule. |
36 | | -Sometimes there are changes or tests that depend on changes in other packages. |
37 | | -If this is the case, there is no way around breaking a single build for a certain period of time. |
38 | | -In this case, run the all tests locally with all the changes and commit them within a time frame of ten minutes. |
39 | | -``` |
40 | | - |
41 | | - |
42 | | -## 2) Always run all commit tests locally before committing |
43 | | - |
44 | | -Follow this practice so the build stays green, and other developers can continue to work without breaking the first rule. |
45 | | - |
46 | | -Remember that Plone development can happen all over the world, at all times. |
47 | | -Other developers may have checked in changes since your last synchronization. |
48 | | -These may interact with your work. |
| 30 | +## Jenkins |
49 | 31 |
|
50 | | -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. |
| 32 | +[Jenkins](https://jenkins.plone.org) is the authoritative source to see whether the complete test suite passes for any Plone version under development. |
| 33 | +Jenkins can be run on a change to any of Plone's hundreds of repositories that it monitors. |
51 | 34 |
|
52 | | -A common source of errors on check-in is to forget to add some files to the repository. |
53 | | -Use {command}`git status` to check and correct for this. |
54 | | -Also double-check to not check in files that should not be part of a package, such as editor configuration files and git submodules. |
55 | 35 |
|
| 36 | +### Run Jenkins |
56 | 37 |
|
57 | | -## 3) Wait for commit tests to pass before moving on |
| 38 | +Running the entire test suite on Jenkins takes at least 30 minutes, and consumes precious server resources. |
| 39 | +For this reason, Jenkins is configured not to run automatically on each push to an open pull request. |
| 40 | +Instead you should wait until you have completed pushing commits to an open pull request, and have seen that all GitHub workflows have passed. |
58 | 41 |
|
59 | | -Always monitor the build's progress, and fix the problem right away if it fails. |
60 | | -If you introduced a regression, you have a far better chance of fixing the build sooner than later. |
61 | | -Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for you. |
62 | | - |
63 | | - |
64 | | -## 4) Never go home on a broken build |
65 | | - |
66 | | -Take into account the first rule of CI ("Don't check in on a broken build"). |
67 | | -Breaking the build essentially stops all other developers from working on it. |
68 | | -Therefore going home on a broken build—or even on a build that has not finished yet—is _not_ acceptable. |
69 | | -It will prevent all other developers from working, or they will need to fix the errors that you introduced. |
| 42 | +After all GitHub checks pass, and if Jenkins monitors the project, you can run Jenkins by adding a comment to the open pull request. |
70 | 43 |
|
| 44 | +```text |
| 45 | +@jenkins-plone-org please run jobs |
| 46 | +``` |
71 | 47 |
|
72 | | -## 5) Always be prepared to revert to the previous revision |
| 48 | +This will trigger Jenkins to run all configured test suites using the changes in the pull request. |
73 | 49 |
|
74 | | -For other developers to work on the build, you should always be prepared to revert to the previous passing revision. |
| 50 | +You can also manually run Jenkins jobs by visiting our [Jenkins server](https://jenkins.plone.org/), logging in with your GitHub account, finding the right job, and clicking the <img alt="Build now icon" src="/_static/contributing/core/icon-build-now.svg" class="inline"> {guilabel}`Build now` button. |
75 | 51 |
|
76 | 52 |
|
77 | | -## 6) Time-box fixing before reverting |
| 53 | +#### `buildout.coredev` special case |
78 | 54 |
|
79 | | -When the build breaks on check-in, try to fix it for ten minutes. |
80 | | -If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. |
81 | | -This way you will allow other developers to continue to work. |
| 55 | +`buildout.coredev` contains the configuration and tooling to orchestrate Plone. |
| 56 | +Contrary to all the other repositories, whenever a push is made to this repository, it automatically triggers Jenkins to run its jobs. |
82 | 57 |
|
83 | 58 |
|
84 | | -## 7) Don't comment out failing tests |
| 59 | +### Results |
85 | 60 |
|
86 | | -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. |
87 | | -While this impulse is understandable, it is _not acceptable_. |
| 61 | +Once a Jenkins job completes, it updates its status icon in the Jenkins UI, and reports the result of the job to the open pull request on GitHub. |
88 | 62 |
|
89 | | -The tests were passing for a while and then start to fail. |
90 | | -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. |
| 63 | +In GitHub at the end of the pull request, a status indicator of either a green check mark {guilabel}`✅` or a red cross {guilabel}`❌` will be displayed for the job, followed by a {guilabel}`Details` link back to the Jenkins job build for that pull request. |
| 64 | +The status indicator will also appear in the GitHub Octocat favicon in the web browser tab on the pull request, and on lists of pull requests. |
91 | 65 |
|
92 | | -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). |
| 66 | +You can use the results to decide whether to merge the pull request. |
93 | 67 |
|
94 | 68 |
|
95 | | -## 8) Take responsibility for all breakages that result from your changes |
| 69 | +### Failure |
96 | 70 |
|
97 | | -If you commit a change and all the tests you wrote pass, but others break, the build is still broken. |
98 | | -This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. |
99 | | -This means that you have introduced a regression bug into the application. |
| 71 | +If the Jenkins job reports a failure, you can investigate its cause. |
| 72 | +Click the {guilabel}`Details` link to show the stacktrace on Jenkins. |
100 | 73 |
|
101 | | -It is _your responsibility_ to fix all tests that do not pass because of your changes. |
| 74 | +In the side bar of the job build page in Jenkins, click the <img alt="Console Output terminal icon" src="/_static/contributing/core/icon-terminal.svg" class="inline"> {guilabel}` Console Output` link to show the full console output. |
| 75 | +You can examine all the steps and debugging information that Jenkins generated while running the job. |
| 76 | +This can be helpful whenever the errors were not in a single test, but rather a test set up or tear down or other problem. |
102 | 77 |
|
103 | | -There are some tests in Plone that fail randomly, and the community is always working on fixing those. |
104 | | -If you think you hit such a test, try to fix it or re-run the Jenkins job to see if it passes again. |
105 | 78 |
|
106 | | -In any case, the developer who made the commit is responsible to make it pass. |
| 79 | +### Retry |
107 | 80 |
|
| 81 | +If there were errors on the Jenkins jobs, and you push additional commits to correct the errors, you can trigger the Jenkins jobs again by adding a comment to the open pull request in GitHub. |
108 | 82 |
|
109 | | -## Further reading |
| 83 | +```text |
| 84 | +@jenkins-plone-org please run jobs |
| 85 | +``` |
110 | 86 |
|
111 | | -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. |
| 87 | +You can also restart Jenkins jobs in the Jenkins UI. |
| 88 | +After logging in to Jenkins, and finding the appropriate job, you can click the <img alt="Retry icon" src="/_static/contributing/core/icon-retry.svg" class="inline"> {guilabel}`Retry` link on the left toolbar to retry the failed job. |
| 89 | +Jenkins will update GitHub statuses accordingly. |
0 commit comments