Skip to content

Commit ee1d9b8

Browse files
lwasserlwasser
authored
feat(content): new pages on CI and pull request to handbook
Add: ci and pr content
2 parents dfc0e63 + baa0063 commit ee1d9b8

File tree

5 files changed

+487
-46
lines changed

5 files changed

+487
-46
lines changed

‎community/github/continuous-integration.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# 3. Continuous integration
2+
3+
## What is CI?
4+
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.
17+
18+
If the repository has code, it will check for code style.
19+
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.
23+
24+
### What do the green and red checks mean?
25+
26+
The green and red checks in the CI block indicate the status of these automated
27+
checks:
28+
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.
36+
37+
#### If a CI check is red
38+
39+
1. **Click on "Details"** next to the failed check to get more information
40+
about the failure.
41+
2. **Review the logs or output** provided to understand what went wrong.
42+
3. **Make the necessary changes** to fix the issue.
43+
4. **Push the updated code** to the pull request to trigger the CI checks
44+
again.
45+
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.
50+
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.
54+
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.
57+
58+
:::{note}
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).
64+
:::
65+
66+
## CI and outside contributors
67+
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!
74+
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.
78+
79+
## Website CI checks
80+
81+
All of our website repositories have several CI builds, including:
82+
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.
90+
91+
(pre-commit-ci)=
92+
## About the Pre-Commit CI Bot
93+
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.
98+
99+
To run the bot on a PR, add the following command to a standalone comment:
100+
101+
`pre-commit autofix`
102+
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.
105+
106+
### What the bot can fix
107+
108+
The bot can in-place fix many linting and style issues in our content,
109+
including:
110+
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/).
116+
117+
### What the bot can’t fix
118+
119+
The bot can't fix some things, such as:
120+
121+
* Logical errors or bugs in the code.
122+
* Issues that require human judgment, such as resolving complex merge
123+
conflicts or making design decisions.
124+
* Spelling errors.
125+
126+
If the bot finds errors that it can't fix, you will need to make those changes
127+
locally.
128+
129+
### Using the bot instead of pre-commit hooks
130+
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.
133+
134+
### Bot setup
135+
136+
To set up the bot in a new repository:
137+
138+
1. **Enable pre-commit.ci** on your repository through the
139+
[pre-commit.ci website](https://pre-commit.ci/).
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.
144+
145+
This approach ensures that all contributions meet our pyOpenSci code and text
146+
quality standards without requiring each contributor to install and run
147+
pre-commit locally.

‎community/github/intro.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# GitHub
1+
# pyOpenSci GitHub Processes
22

33
pyOpenSci has a suite of GitHub repositories (repos) that support pyOpenSci
44
processes and content including:

‎community/github/our-repositories.md

Lines changed: 64 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
# pyOpenSci GitHub Repositories
1+
# pyOpenSci GitHub repositories
2+
23

34
:::{todo}
45
Add repositories from the pyOpenSci organization.
@@ -7,96 +8,114 @@ Add repositories from the pyOpenSci organization.
78
pyOpenSci manages multiple GitHub repositories to support various community
89
activities. Below is a description of each repository.
910

10-
### [Software-review Repository](https://www.pyopensci.org/software-peer-review/)
11+
### [Software-review repository](https://www.pyopensci.org/software-peer-review/)
1112

1213
The software-review repository is where community package submissions are
13-
peer-reviewed. All submissions are made through GitHub Issues. [Learn more about
14-
our peer review process here.](https://www.pyopensci.org/software-peer-review/)
14+
peer-reviewed. All submissions are made through GitHub Issues. [Learn more
15+
about our peer review process here.](https://www.pyopensci.org/software-peer-review/)
1516

1617
:::{important}
1718
Important: If a pyOpenSci core member identifies an issue with the review
18-
submission template, consult both the editorial team and core team before making
19-
any changes. This template's data are processed by a Python workflow, and even
20-
small modifications could disrupt the language processing.
19+
submission template, consult both the editorial team and core team before
20+
making any changes. This template's data are processed by a Python workflow,
21+
and even small modifications could disrupt the language processing.
2122
:::
2223

23-
## Software-peer-review Guidebook Repository
24+
## Software-peer-review guidebook repository
2425

25-
This repository hosts our [software peer review guidebook](https://www.pyopensci.org/software-peer-review/),
26-
which documents the processes and guidelines for authors, editors, the Editor in
27-
Chief, and the peer review triage team as they manage our open peer review process. It also details our peer review policies,
28-
partnerships, and the templates used in the review process.
26+
This repository hosts our [software peer review
27+
guidebook](https://www.pyopensci.org/software-peer-review/), which documents
28+
the processes and guidelines for authors, editors, the Editor in Chief, and the
29+
peer review triage team as they manage our open peer review process. It also
30+
details our peer review policies, partnerships, and the templates used in the
31+
review process.
2932

30-
## Python-package-guide Repository
33+
## Python-package-guide repository
3134

32-
The [python-package-guide repository](https://www.pyopensci.org/python-package-guide/)
33-
contains our community-developed guidelines and tutorials on Python packaging.
34-
These resources are beginner-friendly and reflect Python packaging best practices.
35+
The [python-package-guide
36+
repository](https://www.pyopensci.org/python-package-guide/) contains our
37+
community-developed guidelines and tutorials on Python packaging. These
38+
resources are beginner-friendly and reflect Python packaging best practices.
3539

36-
## [pyosMeta Repository](https://github.com/pyOpenSci/pyosMeta)
40+
## [pyosMeta repository](https://github.com/pyOpenSci/pyosMeta)
3741

38-
The pyosMeta repository contains a Python package published on PyPI that we use to track our
39-
package review and contributor data. This data is used in a GitHub action to
40-
update our website.
42+
The pyosMeta repository contains a Python package published on PyPI that we use
43+
to track our package review and contributor data. This data is used in a GitHub
44+
action to update our website.
4145

4246
:::{todo}
4347
Add more information about the contributor data workflow ...
4448
:::
4549

46-
## [pyopensci.github.io Repository](https://github.com/pyOpenSci/pyopensci.github.io)
50+
## [pyopensci.github.io repository](https://github.com/pyOpenSci/pyopensci.github.io)
4751

48-
This repository contains code and content that builds and publishes our pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is hosted on GitHub and
49-
uses the [Jekyll Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python packages page, contributor page and peer review team page are all updated automagically using a
50-
GitHub action workflow that is supported by the pyosMeta Python package discussed above. The workflow runs every other week but can be triggered manually as a **workflow
51-
dispatch**.
52+
This repository contains code and content that builds and publishes our
53+
pyOpenSci website. The website, [pyOpenSci](https://www.pyopensci.org/), is
54+
hosted on GitHub and uses the [Jekyll Minimal
55+
Mistakes](https://mmistakes.github.io/minimal-mistakes/) theme. The Python
56+
packages page, contributor page, and peer review team page are all updated
57+
automatically using a GitHub action workflow that is supported by the pyosMeta
58+
Python package discussed above. The workflow runs every other week but can be
59+
triggered manually as a **workflow dispatch**.
5260

5361
### Critical CI workflows in this repository
5462

55-
The [contributor workflow action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml) is a custom GitHub
56-
action that is used to update the following website pages:
63+
The [contributor workflow
64+
action](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/.github/workflows/update-contribs-reviews.yml)
65+
is a custom GitHub action that is used to update the following website pages:
5766

5867
* contributor page
5968
* package listing page
60-
* editorial, advisory council and executive council listing
69+
* editorial, advisory council, and executive council listing
6170

62-
It runs as a cron job every other week but also can be run manually as a workflow
63-
dispatch. If you need to update our package listing or contributor list on
64-
the fly, please run this action.
71+
It runs as a cron job every other week but also can be run manually as a
72+
workflow dispatch. If you need to update our package listing or contributor
73+
list on the fly, please run this action.
6574

6675
The action will:
6776

68-
1. parse through all of our accepted pyOpenSci packages
69-
2. collect package names, authors, reviewers and editors
70-
3. collect metadata for the packages authors reviewers and editors using the GitHub (REST) API
77+
1. Parse through all of our accepted pyOpenSci packages.
78+
2. Collect package names, authors, reviewers, and editors.
79+
3. Collect metadata for the package authors, reviewers, and editors using the
80+
GitHub (REST) API.
7181
4. Create 2 output YAML files discussed below.
7282

73-
The YAML output files and then used to populate content on the website.
83+
The YAML output files are then used to populate content on the website.
7484

7585
### Metadata stored in this repository
7686

77-
1. **Packages.yml**: Updates the [Python Packages page](https://www.pyopensci.org/python-packages.html)
78-
by parsing reviews from software-review repository issues.
79-
2. **Contributors.yml**: Updates the [Our Community page](https://www.pyopensci.org/our-community/index.html)
80-
by parsing data from all organization repositories.
87+
1. **Packages.yml**: Updates the [Python Packages
88+
page](https://www.pyopensci.org/python-packages.html) by parsing reviews
89+
from software-review repository issues.
90+
2. **Contributors.yml**: Updates the [Our Community
91+
page](https://www.pyopensci.org/our-community/index.html) by parsing data
92+
from all organization repositories.
8193

8294
:::{todo}
8395
Update the website contributors guide with general CI and specific Jekyll
8496
information.
8597
:::
8698

87-
## [pyOpenSci Sphinx Theme](https://github.com/pyOpenSci/pyos-sphinx-theme)
99+
## [pyOpenSci Sphinx theme](https://github.com/pyOpenSci/pyos-sphinx-theme)
88100

89101
**Platform:** Sphinx book template that builds on top of the pydata_sphinx_theme
90102

91-
All of our pyOpenSci Sphinx books (handbook, packaging guide, software review guide ) have been customized to match our pyOpenSci branding. This repo contains the start of a Sphinx theme that will incorporate all of our branding, so we do not have to manually apply the branding and update it individually in each repo. Instead, we can update branding in the theme and it will be applied across all of our repositories that use the theme.
103+
All of our pyOpenSci Sphinx books (handbook, packaging guide, software review
104+
guide) have been customized to match our pyOpenSci branding. This repo contains
105+
the start of a Sphinx theme that will incorporate all of our branding, so we do
106+
not have to manually apply the branding and update it individually in each repo.
107+
Instead, we can update branding in the theme, and it will be applied across all
108+
of our repositories that use the theme.
92109

93-
Creating a theme was inspired by [Chris Holdgraf's](https://chrisholdgraf.com/) 2i2c Sphinx theme.
110+
Creating a theme was inspired by the
111+
[2i2c Sphinx theme](https://sphinx-2i2c-theme.readthedocs.io/en/latest/).
94112

95-
## [Handbook Repository](https://github.com/pyOpenSci/handbook)
113+
## [Handbook repository](https://github.com/pyOpenSci/handbook)
96114

97-
**Platform:** Sphinx book running the pydata_sphinx_theme
115+
**Platform:** Sphinx book running the `pydata_sphinx_theme`
98116

99-
This is where we store our organization governance, code of conduct and processes around how we operate as an organization.
117+
This is where we store our organization governance, code of conduct, and
118+
processes around how we operate as an organization.
100119

101120
## [pyosPackage repository](https://github.com/pyOpenSci/pyosPackage)
102121

0 commit comments

Comments
 (0)