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: community/github/continuous-integration.md
+85-46Lines changed: 85 additions & 46 deletions
Original file line number
Diff line number
Diff line change
@@ -2,82 +2,119 @@
2
2
3
3
## What is CI?
4
4
5
-
Continuous Integration (CI) refers to checks and tests that are triggered by events that occur on GitHub such as commit pushes, pull requests and even merges to a GitHub repository. In the pyOpenSci organization, each commit
6
-
triggers at least one or more automated CI workflows. For the [pyOpenSci website repository](https://www.pyopensci.org/) and our online books such as the [Python packaging guidebook that is written using Sphinx](https://github.com/pyopensci/python-package-guide), this build will:
7
-
8
-
* build the live rendered version of the online content with any changes added in the current commit(s) or pull requests.
9
-
* check the text for spelling issues, check images for missing alt tags and more.
5
+
Continuous Integration (CI) refers to checks and tests that are triggered by
6
+
events that occur on GitHub such as commit pushes, pull requests, and even
7
+
merges to a GitHub repository. In the pyOpenSci organization, each commit
8
+
triggers at least one or more automated CI workflows. For the [pyOpenSci
9
+
website repository](https://www.pyopensci.org/) and our online books such as
10
+
the [Python packaging guidebook that is written using
11
+
Sphinx](https://github.com/pyopensci/python-package-guide), this build will:
12
+
13
+
* Build the live rendered version of the online content with any changes added
14
+
in the current commit(s) or pull requests.
15
+
* Check the text for spelling issues, check images for missing alt tags, and
16
+
more.
10
17
11
18
If the repository has code, it will check for code style.
12
19
13
-
Having a CI setup on each pyOpenSci GitHub repository ensures that we detect issues such as bad links or broken code before they're merged into the main repository.
20
+
Having a CI setup on each pyOpenSci GitHub repository ensures that we detect
21
+
issues such as bad links or broken code before they're merged into the main
22
+
repository.
14
23
15
24
### What do the green and red checks mean?
16
25
17
26
The green and red checks in the CI block indicate the status of these automated
18
27
checks:
19
28
20
-
***Green Checks**: These indicate that the code has passed the CI checks. This means the code meets the project's standards and is likely
21
-
free from errors or issues related to the specific checks that have passed.
22
-
23
-
***Red X's**: These indicate that the code has failed the associated CI checks. This means there are issues that need to be addressed before the code can be merged. The issues could be related to code style, formatting, tests, or other criteria specified by the CI configuration.
29
+
***Green checks**: These indicate that the code has passed the CI checks.
30
+
This means the code meets the project's standards and is likely free from
31
+
errors or issues related to the specific checks that have passed.
32
+
***Red X's**: These indicate that the code has failed the associated CI
33
+
checks. This means there are issues that need to be addressed before the code
34
+
can be merged. The issues could be related to code style, formatting, tests,
35
+
or other criteria specified by the CI configuration.
24
36
25
37
#### If a CI check is red
26
38
27
-
1.**Click on "Details"** next to the failed check to get more information about the failure.
39
+
1.**Click on "Details"** next to the failed check to get more information
40
+
about the failure.
28
41
2.**Review the logs or output** provided to understand what went wrong.
29
42
3.**Make the necessary changes** to fix the issue.
30
-
4.**Push the updated code** to the pull request to trigger the CI checks again.
43
+
4.**Push the updated code** to the pull request to trigger the CI checks
44
+
again.
31
45
32
-
If something isn't working as expected or you are having a hard time understanding why CI is failing (we've all been there!), please ping someone else in the organization for help. As a pyOpenSci community, we are always here to help each other.
46
+
If something isn't working as expected or you are having a hard time
47
+
understanding why CI is failing (we've all been there!), please ping someone
48
+
else in the organization for help. As a pyOpenSci community, we are always
49
+
here to help each other.
33
50
34
-
If all CI checks are green, you are good to go. Ping a pyOpenSci repository owner on GitHub to review your pull request. The pull request can be merged once you have approval from another repository owner.
51
+
If all CI checks are green, you are good to go. Ping a pyOpenSci repository
52
+
owner on GitHub to review your pull request. The pull request can be merged
53
+
once you have approval from another repository owner.
35
54
36
-
If you don't know who to ping, no worries. Someone from the pyOpenSci organization will see your pull request and get back to you.
55
+
If you don't know who to ping, no worries. Someone from the pyOpenSci
56
+
organization will see your pull request and get back to you.
37
57
38
58
:::{note}
39
-
Generally we require a single passing approval in order to merge a pull request. However, in some cases, if you are a pyOpenSci staff member or community member with admin / write access, it could be the case that you need to merge something immediately (i.e. fixing a small piece of breaking code, a spelling error, or adding a new piece of content that has already been agreed upon).
59
+
Generally, we require a single passing approval to merge a pull request.
60
+
However, in some cases, if you are a pyOpenSci staff member or community
61
+
member with admin/write access, it could be the case that you need to merge
62
+
something immediately (i.e., fixing a small piece of breaking code, a spelling
63
+
error, or adding a new piece of content that has already been agreed upon).
40
64
:::
41
65
42
66
## CI and outside contributors
43
67
44
-
If someone from outside of the pyOpenSci organization submits a pull request, then someone within the organization needs to approve and run CI. If you
45
-
have those super powers, please go ahead and allow CI to run for new contributors. You can’t break anything by running CI, so always feel confident in our repos when you click that button, assuming that the PR is legitimate and submitted from a valid user!
68
+
If someone from outside of the pyOpenSci organization submits a pull request,
69
+
then someone within the organization needs to approve and run CI. If you have
70
+
those superpowers, please go ahead and allow CI to run for new contributors.
71
+
You can’t break anything by running CI, so always feel confident in our repos
72
+
when you click that button, assuming that the PR is legitimate and submitted
73
+
from a valid user!
46
74
47
-
Next to each CI step that was run, there is a details button. If you click on that link, it will give you more information about what has run / not run as expected in the build.
75
+
Next to each CI step that was run, there is a details button. If you click on
76
+
that link, it will give you more information about what has run/not run as
77
+
expected in the build.
48
78
49
79
## Website CI checks
50
80
51
-
All of our website repositories have several CI builds including:
81
+
All of our website repositories have several CI builds, including:
52
82
53
-
1. A link checker
54
-
2.`htmlproofer`, which checks both links and alt tags, as well as images
55
-
3. a CI build that shows you what the rendered site looks like when built online. Currently we are using [CircleCI](https://circleci.com/) for a live rendered build, as CircleCI allows for in-browser website build checks. GitHub requires you to download, unzip and view and archive with the build site locally.
83
+
1. A link checker.
84
+
2.`htmlproofer`, which checks both links and alt tags, as well as images.
85
+
3. A CI build that shows you what the rendered site looks like when built
86
+
online. Currently, we are using [CircleCI](https://circleci.com/) for a
87
+
live rendered build, as CircleCI allows for in-browser website build checks.
88
+
GitHub requires you to download, unzip, and view an archive with the build
89
+
site locally.
56
90
57
91
(pre-commit-ci)=
58
-
59
92
## About the Pre-Commit CI Bot
60
93
61
-
The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration service that automatically
62
-
runs pre-commit hooks on each pull request. This helps maintain code quality
63
-
and consistency without requiring developers to run pre-commit locally.
94
+
The [Pre-commit CI bot](https://pre-commit.ci/) is a continuous integration
95
+
service that automatically runs pre-commit hooks on each pull request. This
96
+
helps maintain code quality and consistency without requiring developers to
97
+
run pre-commit locally.
64
98
65
99
To run the bot on a PR, add the following command to a standalone comment:
66
100
67
101
`pre-commit autofix`
68
102
69
-
When you do this, the bot will run all of the hooks that it can, adding
70
-
a new commit to the pull request for you.
103
+
When you do this, the bot will run all of the hooks that it can, adding a new
104
+
commit to the pull request for you.
71
105
72
-
####What the Bot Can Fix
106
+
### What the bot can fix
73
107
74
-
The bot can in-place fix many linting and style issues in our content, including:
108
+
The bot can in-place fix many linting and style issues in our content,
109
+
including:
75
110
76
-
* Automatically fixing formatting issues such as trailing whitespace and missing
77
-
newlines.
78
-
* Apply code style adjustments as specified by hooks like [`black`](https://github.com/psf/black) and [`isort`](https://pycqa.github.io/isort/).
111
+
* Automatically fixing formatting issues such as trailing whitespace and
112
+
missing newlines.
113
+
* Applying code style adjustments as specified by hooks like
114
+
[`black`](https://github.com/psf/black) and
115
+
[`isort`](https://pycqa.github.io/isort/).
79
116
80
-
####What the Bot Can’t Fix
117
+
### What the bot can’t fix
81
118
82
119
The bot can't fix some things, such as:
83
120
@@ -86,23 +123,25 @@ The bot can't fix some things, such as:
86
123
conflicts or making design decisions.
87
124
* Spelling errors.
88
125
89
-
In the case that the bot finds errors that it can't fix, you will need to
90
-
make those changes locally.
126
+
If the bot finds errors that it can't fix, you will need to make those changes
127
+
locally.
91
128
92
-
### Using the Bot Instead
129
+
### Using the bot instead of pre-commit hooks
93
130
94
-
pyOpenSci contributors may prefer not to set up pre-commit locally. In that case,
95
-
we can rely on the pre-commit.ci bot to fix things as needed.
131
+
pyOpenSci contributors may prefer not to set up pre-commit locally. In that
132
+
case, we can rely on the pre-commit.ci bot to fix things as needed.
96
133
97
-
####Bot setup
134
+
### Bot setup
98
135
99
-
To setup the bot in a new repository:
136
+
To set up the bot in a new repository:
100
137
101
138
1.**Enable pre-commit.ci** on your repository through the
102
139
[pre-commit.ci website](https://pre-commit.ci/).
103
-
2. The pre-commit.ci bot will automatically run checks and apply fixes on pull requests.
104
-
3. Review the bot's output and ensure all checks pass before merging your code.
140
+
2. The pre-commit.ci bot will automatically run checks and apply fixes on
141
+
pull requests.
142
+
3. Review the bot's output and ensure all checks pass before merging your
143
+
code.
105
144
106
-
This approach ensures that all contributions meet our pyOpenSci code and
107
-
text quality standards without requiring each contributor to install and run
145
+
This approach ensures that all contributions meet our pyOpenSci code and text
146
+
quality standards without requiring each contributor to install and run
0 commit comments