|
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 | | -# Continuous Integration |
| 10 | +# Continuous integration |
11 | 11 |
|
12 | | -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. |
| 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 | | -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. |
| 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. |
15 | 17 |
|
16 | | -## Jenkins |
17 | 18 |
|
18 | | -Jenkins is the primary source of truth to know if the complete test suite of any Plone versions in development is passing or not. |
| 19 | +## GitHub workflows |
| 20 | + |
| 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 | + |
| 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. |
19 | 26 |
|
20 | | -Jenkins is configured to react on changes done in any of the hundreds of repositories that all together make Plone. |
| 27 | +GitHub workflows should pass before running Jenkins checks and before merging an open pull request. |
21 | 28 |
|
22 | | -Whenever a change on any of those repositories happen, Jenkins starts a slew of testing jobs that ultimately answer the question of if those changes pass Plone's test suite. |
23 | 29 |
|
24 | | -### Triggering jobs (automatically) |
| 30 | +## Jenkins |
| 31 | + |
| 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. |
25 | 34 |
|
26 | | -As running the Jenkins jobs is a bit expensive, in time, Jenkins does not run automatically on any new commit. |
27 | 35 |
|
28 | | -Rather, Jenkins waits for a special comment to be found in a pull request on a repository that is monitored by Jenkins. |
| 36 | +### Run Jenkins |
| 37 | + |
| 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. |
| 41 | + |
| 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. |
29 | 43 |
|
30 | 44 | ```text |
31 | 45 | @jenkins-plone-org please run jobs |
32 | 46 | ``` |
33 | 47 |
|
34 | | -Pasting the text above on a pull request, will trigger Jenkins to run all configured test suites related to the current pull request, **with the changes of the pull request itself**. |
| 48 | +This will trigger Jenkins to run all configured test suites using the changes in the pull request. |
35 | 49 |
|
36 | | -#### buildout.coredev special case |
| 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. |
37 | 51 |
|
38 | | -`buildout.coredev` is the special repository where our configuration and tooling to orchestrate Plone lies in. |
39 | 52 |
|
40 | | -Contrary to all the other repositories, whenever a commit is made on this repository, it automatically triggers Jenkins jobs to be run. |
| 53 | +#### `buildout.coredev` special case |
41 | 54 |
|
42 | | -### Triggering jobs (manually) |
| 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. |
43 | 57 |
|
44 | | -Jenkins jobs can also be triggered manually by going to our Jenkins server, login in with your GitHub account, finding the right job, and triggering the `Run` button. |
45 | 58 |
|
46 | 59 | ### Results |
47 | 60 |
|
48 | | -Once a jenkins job is finished, it will update its status icon on Jenkins UI itself, but also report back to GitHub, the result of the job. |
| 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. |
49 | 62 |
|
50 | | -For pull requests, this means a green check mark or a red cross will be displayed at the end of the pull request, on pull requests listings, even on the favicon itself. |
| 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. |
51 | 65 |
|
52 | | -This gives the expected feedback to the pull request author, or any reviewer interested in knowing how a given pull request fared in Jenkins. Thus allowing pull request reviewers or authors to decide if the pull request can already be merged. |
| 66 | +You can use the results to decide whether to merge the pull request. |
53 | 67 |
|
54 | | -#### On failures |
55 | 68 |
|
56 | | -If the Jenkins jobs reports failures, the statuses of the pull request will provide a `Details` link back to Jenkins. |
| 69 | +### Failure |
57 | 70 |
|
58 | | -That link leads back to the Jenkins job build for that pull request. |
| 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. |
59 | 73 |
|
60 | | -In that page, there is the list of test failures (if any) already listed. Clicking on them show the stacktrace that should help diagnose why there was an error on a given test. |
| 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. |
61 | 77 |
|
62 | | -On the side bar of the job build page in Jenkins there is also `Console Output` link. This leads to the **full job output**, note that is large, where it can be seen all the steps and debugging information that Jenkins generated running the job. |
63 | 78 |
|
64 | | -This can be helpful whenever the errors where not on a single test, but rather a general testing set up/tear down problem. |
| 79 | +### Retry |
65 | 80 |
|
66 | | -### Retrying |
67 | | - |
68 | | -If there were errors on the Jenkins jobs, and corrections have been made on the code, triggering the jenkins jobs again is a matter of giving the special comment on the GitHub pull request again: |
| 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. |
69 | 82 |
|
70 | 83 | ```text |
71 | 84 | @jenkins-plone-org please run jobs |
72 | 85 | ``` |
73 | 86 |
|
74 | | -Jenkins jobs can also be restarted within Jenkins UI itself. On the Jenkins job itself, and provided you are logged in, you can find a `Retry` link on the left toolbar. Clicking it will trigger a new Jenkins job with the same configuration as the one you are on. |
75 | | - |
| 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. |
76 | 89 | Jenkins will update GitHub statuses accordingly. |
0 commit comments