You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: coredev/continous-integration.md
+37-44Lines changed: 37 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,114 +7,107 @@ myst:
7
7
"keywords": ""
8
8
---
9
9
10
-
% -*- coding: utf-8 -*-
10
+
# Essential continuous integration practices
11
11
12
-
# Essential Continuous Integration Practices
13
-
14
-
The CI system at [jenkins.plone.org](http://jenkins.plone.org) is a shared resource for Plone core developers
15
-
to notify them of regressions in Plone core code.
12
+
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.
16
13
17
14
Build breakages are a normal and expected part of the development process.
18
15
Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors.
19
16
Though, there are some essential rules that needs to be followed in order to achieve a stable build.
20
17
21
-
## 1) Don’t Check In on a Broken Build
18
+
19
+
## 1) Don't check in on a broken build
22
20
23
21
Do not make things more complicated for the developer who is responsible for breaking the build.
24
22
25
23
If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it.
26
24
27
25
If we adopt this strategy, we will always be in the best position to find out what caused the breakage and fix it immediately.
28
26
29
-
If one of the developers has made a check-in and broken the build as a result, we have the best chance of fixing
30
-
the build if we have a clear look at the problem.
27
+
If one of the developers has made a check-in and broken the build as a result, we have the best chance of fixing the build if we have a clear look at the problem.
31
28
32
29
Checking in further changes and triggering new builds will just lead to more problems.
33
30
34
-
If the build is broken over a longer period of time (more than a couple of hours)
35
-
you should either notify the developer who is responsible for the breakage, fix the problem yourself,
36
-
or just revert the commit in order to be able to continue to work.
31
+
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, or just revert the commit in order to be able to continue to work.
37
32
38
-
:::{note}
33
+
```note
39
34
There is one exception to this rule.
40
35
Sometimes there are changes or tests that depend on changes in other packages.
41
-
If this is the case,
42
-
there is no way around breaking a single build for a certain period of time.
36
+
If this is the case, there is no way around breaking a single build for a certain period of time.
43
37
In this case run the all tests locally with all the changes and commit them within a time frame of 10 minutes.
44
-
:::
38
+
```
39
+
45
40
46
-
## 2) Always Run All Commit Tests Locally before Committing
41
+
## 2) Always run all commit tests locally before committing
47
42
48
43
Following this practice ensures the build stays green and other developers can continue to work without breaking the first rule.
49
44
50
-
There might be changes that have been checked in before your last update from the version control that might
51
-
lead to a build failure in Jenkins in combination with your changes.
45
+
There might be changes that have been checked in before your last update from the version control that might lead to a build failure in Jenkins in combination with your changes.
52
46
53
47
Therefore it is essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub.
54
48
55
49
Furthermore, a common source of errors on check-in is to forget to add some files to the repository.
56
50
57
-
If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime,
58
-
or because you forgot to add a new class or configuration file that you have been working on into the version control system.
51
+
If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system.
59
52
60
-
## 3) Wait for Commit Tests to Pass before Moving On
61
53
62
-
Always monitor the build’s progress and fix the problem right away if it fails.
54
+
## 3) Wait for commit tests to pass before moving on
55
+
56
+
Always monitor the build's progress and fix the problem right away if it fails.
63
57
64
58
You have a far better chance of fixing the build, if you just introduced a regression than later.
65
-
Also another developer might have committed in the meantime (by breaking rule 1)
66
-
making things more complicated for your.
59
+
Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours.
60
+
67
61
68
-
## 4) Never Go Home on a Broken Build
62
+
## 4) Never go home on a broken build
69
63
70
-
Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially
71
-
stops all other developers from working on it.
64
+
Taking 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.
72
65
73
66
Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable.
74
67
It will prevent all the other developers to stop working on the build or fixing the errors that you introduced.
75
68
76
-
## 5) Always Be Prepared to Revert to the Previous Revision
77
69
78
-
In order for the other developers to be able to work on the build, you should always be prepared to revert
79
-
to the previous (passing) revision.
70
+
## 5) Always be prepared to revert to the previous revision
80
71
81
-
## 6) Time-Box Fixing before Reverting
72
+
In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision.
73
+
74
+
75
+
## 6) Time-box fixing before reverting
82
76
83
77
When the build breaks on check-in, try to fix it for ten minutes.
84
-
If, after ten minutes, you aren’t finished with the solution, revert to the previous version from your version control system.
78
+
If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system.
85
79
This way you will allow other developers to continue to work.
86
80
87
-
## 7) Don’t Comment Out Failing Tests
88
81
89
-
Once you begin to enforce the previous rule, the result is often that developers start commenting out
90
-
failing tests in order to get the build passing again as quick as possible.
82
+
## 7) Don't comment out failing tests
83
+
84
+
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 quick as possible.
91
85
92
86
While this impulse is understandable, it is **wrong**.
93
87
94
88
The tests have been passing for a while and then start to fail.
95
-
This means that we either caused a regression, made assumptions that are no longer valid,
96
-
or the application has changed the functionality being tested for a valid reason.
89
+
This means that we either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason.
97
90
98
-
You should always either fix the code (if a regression has been found), modify the test
99
-
(if one of the assumptions has changed), or delete it (if the functionality under test no longer exists).
91
+
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).
100
92
101
-
## 8) Take Responsibility for All Breakages That Result from Your Changes
93
+
94
+
## 8) Take responsibility for all breakages that result from your changes
102
95
103
96
If you commit a change and all the tests you wrote pass, but others break, the build is still broken.
104
97
This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on.
105
98
106
99
This means that you have introduced a regression bug into the application.
107
100
108
-
It is **your responsibility** — because you made the change — to fix all tests that are not passing as a result of your changes.
101
+
It is **your responsibility**—because you made the change—to fix all tests that are not passing as a result of your changes.
109
102
110
103
There are some tests in Plone that fail randomly, we are always working on fixing those.
111
104
If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again.
112
105
113
106
In any case the developer who made the commit is responsible to make it pass.
114
107
108
+
115
109
## Further Reading
116
110
117
-
Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley),
118
-
and have been adopted and rewritten for the Plone community.
111
+
Those 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.
119
112
120
-
If you want to learn more about Continuous Integration and Continuous Delivery, I'd recommend that you buy this book.
113
+
If you want to learn more about continuous integration and continuous delivery, I'd recommend that you buy this book.
0 commit comments