Skip to content

Commit b23989d

Browse files
jt14denjt14den
authored
Merge pull request #52 from UC-OSPO-Network/docs/update-readme-contributing
docs: Update README and CONTRIBUTING with project details
2 parents 4510262 + 04da819 commit b23989d

File tree

4 files changed

+299
-74
lines changed

4 files changed

+299
-74
lines changed

‎.github/workflows/pr-check.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Pull Request Build Check
2+
# Runs comprehensive tests on PRs to ensure changes don't break the site
3+
# Checks: TypeScript, build, data validation, links, and critical pages
4+
name: PR Build Check
5+
6+
on:
7+
pull_request_target:
8+
branches: [ main ]
9+
paths:
10+
- 'src/**'
11+
- 'public/**'
12+
- 'astro.config.mjs'
13+
- 'package*.json'
14+
- 'tsconfig.json'
15+
- '.github/workflows/pr-check.yml'
16+
- '.github/scripts/**'
17+
18+
# Limit permissions for security
19+
permissions:
20+
contents: read
21+
pull-requests: write
22+
issues: write
23+
24+
jobs:
25+
validate:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout PR branch
29+
uses: actions/checkout@v4
30+
with:
31+
ref: ${{ github.event.pull_request.head.sha }}
32+
33+
- name: Setup Node.js
34+
uses: actions/setup-node@v4
35+
with:
36+
node-version: '20'
37+
cache: 'npm'
38+
39+
- name: Install dependencies
40+
run: npm ci
41+
42+
# ============================================
43+
# Step 1: Validate Google Sheets data source
44+
# ============================================
45+
- name: Validate data source
46+
run: node .github/scripts/validate-data.mjs
47+
continue-on-error: false
48+
49+
# ============================================
50+
# Step 2: TypeScript validation
51+
# ============================================
52+
- name: Run Astro check
53+
run: npx astro check
54+
continue-on-error: false
55+
56+
# ============================================
57+
# Step 3: Build the site
58+
# ============================================
59+
- name: Build site
60+
run: npm run build
61+
continue-on-error: false
62+
63+
# ============================================
64+
# Step 4: Validate build output
65+
# ============================================
66+
- name: Validate build output
67+
run: node .github/scripts/validate-build.mjs
68+
continue-on-error: false
69+
70+
# ============================================
71+
# Step 5: Check internal links
72+
# ============================================
73+
- name: Check internal links
74+
run: node .github/scripts/check-links.mjs
75+
continue-on-error: false
76+
77+
# ============================================
78+
# Step 6: Report success/failure
79+
# ============================================
80+
- name: Comment PR with success
81+
if: success()
82+
uses: actions/github-script@v7
83+
with:
84+
script: |
85+
const body = `## ✅ All PR checks passed!
86+
87+
| Check | Status |
88+
|-------|--------|
89+
| 📊 Data validation | ✅ Pass |
90+
| 🔍 TypeScript check | ✅ Pass |
91+
| 🏗️ Build | ✅ Pass |
92+
| 📄 Critical pages | ✅ Pass |
93+
| 🔗 Internal links | ✅ Pass |
94+
95+
The site builds successfully and all validation checks passed.`;
96+
97+
github.rest.issues.createComment({
98+
issue_number: context.issue.number,
99+
owner: context.repo.owner,
100+
repo: context.repo.repo,
101+
body: body
102+
})
103+
104+
- name: Comment PR with failure
105+
if: failure()
106+
uses: actions/github-script@v7
107+
with:
108+
script: |
109+
const body = `## ❌ PR checks failed
110+
111+
One or more validation checks failed. Please review the [workflow logs](${context.payload.repository.html_url}/actions/runs/${context.runId}) to see what went wrong.
112+
113+
Common issues:
114+
- 📊 **Data validation**: Google Sheets CSV is unreachable or has invalid data
115+
- 🔍 **TypeScript check**: Type errors in code
116+
- 🏗️ **Build**: Build process failed
117+
- 📄 **Critical pages**: Missing required pages (index, lessons, pathways)
118+
- 🔗 **Internal links**: Broken links detected`;
119+
120+
github.rest.issues.createComment({
121+
issue_number: context.issue.number,
122+
owner: context.repo.owner,
123+
repo: context.repo.repo,
124+
body: body
125+
})

‎CONTRIBUTING.md‎

Lines changed: 95 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,23 @@
1-
# CONTRIBUTING
2-
3-
[TODO: rename this file to `README.md`; i.e. remove the template reference]
4-
5-
This is a template document for UC projects can use to help build the documentation in your project repos. It requires editing before it is ready to use, and you can find guides for using these templates on [our website](https://ucospo.net/oss-resources/#template-guides). Please feel free to [reach out to our Laura](mailto:lalangdon@ucdavis.edu), our Community Manager, if you have any questions!
6-
7-
Search for the word `TODO` in this template to identify parts that require customization; e.g. line 3 above lets you know you should rename this file.. When you finish editing the template, remove the `TODO` bits.
8-
9-
[TODO: delete the lines between line 1 and the "Welcome" heading]
1+
# Contributing to UC OSPO Education Website
102

113
## Welcome!
124

13-
[TODO: edit welcome text below]
5+
Welcome! We're glad you want to contribute to the UC OSPO Education Lesson & Pathways project! 💖
146

15-
Welcome! We're glad you want to contribute to our project! 💖
7+
This project is part of the UC OSPO Network's education subgroup, working to curate and organize open source education resources from The Carpentries, CodeRefinery, and other sources.
168

179
As you get started, you're in the best position to give us feedback on areas of our project that we need help with including:
1810

1911
* Problems found during setting up a new developer environment
20-
* Gaps in our Quickstart Guide or documentation
21-
* Bugs in our automation scripts
12+
* Gaps in our documentation or README
13+
* Issues with the lesson data or Google Sheets integration
14+
* Bugs in our validation scripts or build process
15+
* Ideas for improving lesson discovery and navigation
2216

2317
If anything doesn't make sense, or doesn't work when you run it, please open a bug report and let us know!
2418

2519
## Table of Contents
2620

27-
[TODO: edit the Table of Contents]
28-
2921
* [Ways to Contribute](#ways-to-contribute)
3022
* [Come to Community Calls](#come-to-community-calls)
3123
* [Finding an Issue](#finding-an-issue)
@@ -38,89 +30,137 @@ If anything doesn't make sense, or doesn't work when you run it, please open a b
3830

3931
## Ways to Contribute
4032

41-
[TODO: edit this to reflect the kinds of contributions you'd like to receive for your project]
42-
4333
We welcome many different types of contributions, including:
4434

45-
* New features
46-
* Builds, CI/CD
47-
* Bug fixes
48-
* Documentation
49-
* Issue Triage
50-
* Answering questions on Slack/Mailing List
51-
* Web design
52-
* Communications/Social Media/Blog Posts
53-
* Release management
35+
* **Lesson Curation**: Help identify, review, and add lessons to our inventory
36+
* **Content Enhancement**: Improve lesson descriptions, metadata, and categorization
37+
* **Feature Development**: Build new features for lesson discovery and navigation
38+
* **Data Quality**: Help validate and improve our Google Sheets data
39+
* **Bug Fixes**: Fix issues in the build process, validation scripts, or site functionality
40+
* **Documentation**: Improve our README, contributing guide, or inline documentation
41+
* **Testing**: Help test PR previews and report issues
42+
* **Web Design**: Enhance the visual design and user experience
43+
* **Accessibility**: Improve accessibility features and compliance
44+
* **Issue Triage**: Help organize and prioritize GitHub issues
5445

55-
Not everything happens through a GitHub pull request. Please come to our meetings](TODO) or [contact us](/UC-OSPO-Network/templates/blob/d8ba9301beb523c10a7195ddf0fb70a068312022/TODO) and let's discuss how we can work together.
46+
Not everything happens through a GitHub pull request. Please come to our [education subgroup meetings](https://docs.google.com/document/d/1-CJxDt05f9YoYfGB8-NC0zvQZbEJzHT1P7keRciMlrY/edit?tab=t.0#heading=h.vs4sjkl9adbl) or open a [GitHub Discussion](https://github.com/UC-OSPO-Network/education/discussions) and let's discuss how we can work together.
5647

57-
## Come to Community Calls
48+
## Come to Education Subgroup Meetings
5849

59-
[TODO: Maybe your project doesn't have [community calls](https://opensource.com/open-organization/16/1/community-calls-will-increase-participation-your-open-organization), in which case you can omit this section. But you might consider trying them out!]
50+
Anyone interested in our project is welcome to join our [education subgroup meetings](https://docs.google.com/document/d/1-CJxDt05f9YoYfGB8-NC0zvQZbEJzHT1P7keRciMlrY/edit?tab=t.0#heading=h.vs4sjkl9adbl)! You never need an invite to join us. In fact, we want you to join us, even if you don't have anything you feel like you want to contribute. Just being there is enough!
6051

61-
Anyone interested in our project is welcome to come to any of [our community calls](TODO: add a link to your community calls)! You never need an invite to join us. In fact, we want you to join us, even if you don’t have anything you feel like you want to contribute. Just being there is enough!
52+
Check our [meeting notes](https://docs.google.com/document/d/1-CJxDt05f9YoYfGB8-NC0zvQZbEJzHT1P7keRciMlrY/edit?tab=t.0#heading=h.vs4sjkl9adbl) for the meeting schedule, Zoom link, and past discussions.
6253

63-
You don’t have to turn on your video. The first time you come, just introducing yourself is perfectly fine. Over time, we hope that you feel comfortable voicing your opinions, giving feedback on others’ ideas, and even sharing your own ideas, and experiences.
54+
You don't have to turn on your video. The first time you come, just introducing yourself is perfectly fine. Over time, we hope that you feel comfortable voicing your opinions, giving feedback on others' ideas, and even sharing your own ideas and experiences.
6455

6556
## Finding an Issue
6657

67-
[TODO: edit this section as needed]
58+
We have good first issues for new contributors and help wanted issues suitable for any contributor:
6859

69-
We have good first issues for new contributors and help wanted issues suitable for any contributor. [good first issue](/UC-OSPO-Network/templates/blob/d8ba9301beb523c10a7195ddf0fb70a068312022/TODO) has extra information to help you make your first contribution. [help wanted](/UC-OSPO-Network/templates/blob/d8ba9301beb523c10a7195ddf0fb70a068312022/TODO) are issues suitable for someone who isn't a core maintainer and is good to move onto after your first pull request.
60+
* [good first issue](https://github.com/UC-OSPO-Network/education/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - Issues with extra information to help you make your first contribution
61+
* [help wanted](https://github.com/UC-OSPO-Network/education/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) - Issues suitable for any contributor
7062

71-
Sometimes there won’t be any issues with these labels. That’s ok! There is likely still something for you to work on. If you want to contribute but you don’t know where to start or can't find a suitable issue, you can [TODO: explain how people can ask for an issue to work on].
63+
Sometimes there won't be any issues with these labels. That's ok! There is likely still something for you to work on. If you want to contribute but you don't know where to start or can't find a suitable issue, you can:
64+
65+
* Open a [GitHub Discussion](https://github.com/UC-OSPO-Network/education/discussions) asking where help is needed
66+
* Comment on an existing issue asking if it's available to work on
67+
* Join our [education subgroup meetings](https://docs.google.com/document/d/1-CJxDt05f9YoYfGB8-NC0zvQZbEJzHT1P7keRciMlrY/edit?tab=t.0#heading=h.vs4sjkl9adbl) and ask there
7268

7369
Once you see an issue that you'd like to work on, please post a comment saying that you want to work on it. Something like "I want to work on this" is fine.
7470

7571
## Setting up a Dev Environment
7672

77-
[TODO: edit the steps provided for what's needed for your project]
73+
**Prerequisites:**
74+
* Node.js (version 20 or higher)
75+
* npm (Node Package Manager)
76+
* Git
77+
78+
**Steps:**
79+
80+
1. Clone the project:
81+
82+
```shell
83+
git clone https://github.com/UC-OSPO-Network/education.git
84+
cd education
85+
```
7886

79-
Clone the project:
87+
2. Install dependencies:
8088

8189
```shell
82-
git clone yourprojecturl
90+
npm install
8391
```
8492

85-
Install dependencies:
93+
3. Start the development server:
8694

8795
```shell
88-
install command
96+
npm run dev
8997
```
9098

99+
This will start a local development server at `http://localhost:4321`.
100+
91101
## Running Tests
92102

93-
[TODO: Describe the process you use to test code in your project]
103+
Before submitting your pull request, run these validation checks locally:
104+
105+
1. **Validate data source:**
106+
```shell
107+
node .github/scripts/validate-data.mjs
108+
```
109+
110+
2. **Run TypeScript type checking:**
111+
```shell
112+
npx astro check
113+
```
114+
115+
3. **Build the site:**
116+
```shell
117+
npm run build
118+
```
119+
120+
4. **Validate build output:**
121+
```shell
122+
node .github/scripts/validate-build.mjs
123+
```
94124

95-
1. Step one
96-
2. Step two
125+
5. **Check for broken links:**
126+
```shell
127+
node .github/scripts/check-links.mjs
128+
```
129+
130+
These checks run automatically on pull requests via GitHub Actions. Make sure they all pass locally to avoid failed PR checks.
97131

98132
## Asking for Help
99133

100134
The best way to reach us with a question when contributing is to ask on:
101135

102-
[TODO: Pick the way(s) that you prefer people ask for help]
103-
104-
* The original Github issue
105-
* The developer mailing list
106-
* Our Slack channel
136+
* **The original GitHub issue** - Comment on the issue you're working on
137+
* **[GitHub Discussions](https://github.com/UC-OSPO-Network/education/discussions)** - For general questions
138+
* **[Education subgroup meetings](https://docs.google.com/document/d/1-CJxDt05f9YoYfGB8-NC0zvQZbEJzHT1P7keRciMlrY/edit?tab=t.0#heading=h.vs4sjkl9adbl)** - Join us at our regular meetings
107139

108140
## Norms for Commits
109141

110-
[TODO: edit this section to reflect what's needed for your project]
142+
We encourage clear, descriptive commit messages that explain what changed and why:
111143

112-
Our project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), and we require [commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). Please let us know if you need help with these!
144+
* Use present tense ("Add feature" not "Added feature")
145+
* Use imperative mood ("Fix bug" not "Fixes bug")
146+
* Include context when helpful ("Fix broken link in pathways page")
147+
* Reference issues when applicable ("Fixes #123")
113148

114-
## Pull Request Lifecycle
149+
Optionally, consider using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (e.g., `feat:`, `fix:`, `docs:`) for consistency.
115150

116-
[TODO: Edit the text below to describe your pull request process. You don't need to adopt every aspect! Pick and choose what makes sense for *your* project]
151+
## Pull Request Lifecycle
117152

118153
### Before You Submit
119154

120-
When you submit your pull request, or you push new commits to it, our automated systems will run some checks on your new code. We require that your pull request passes these checks, but we also have more criteria than just that before we can accept and merge it. We recommend that you check the following things locally before you submit your code:
155+
When you submit your pull request, or push new commits to it, our automated systems will run validation checks on your code. We require that your pull request passes these checks before we can merge it. We recommend that you run the following locally before submitting:
156+
157+
* **Data validation** - Ensure Google Sheets data is accessible and valid
158+
* **TypeScript check** - Run `npx astro check` to catch type errors
159+
* **Build** - Run `npm run build` to ensure the site builds successfully
160+
* **Critical pages** - Verify required pages exist after building
161+
* **Link checking** - Ensure no broken internal links
121162

122-
* First thing to check
123-
* Another thing to check
163+
All pull requests will automatically get a preview deployment via Vercel so reviewers can see your changes live.
124164

125165
#### When to Submit
126166

@@ -214,4 +254,4 @@ Watch the repository to be notified when your contributions are released. We'll
214254

215255
## Code of Conduct
216256

217-
Please read our [Code of Conduct](TODO: link to your project's CoC)
257+
Please read our [Code of Conduct](CODE_OF_CONDUCT.md) to understand the expectations for behavior within our community. We are committed to providing a welcoming and inclusive environment for all contributors.

0 commit comments

Comments
 (0)