How to Contribute to the OSSU Computer Science Repository: A Complete Guide

To contribute to the OSSU computer science repository, fork the repository, create a feature branch, edit the relevant Markdown files in the Jekyll-based curriculum structure, and submit a pull request that follows the standards defined in CONTRIBUTING.md and CURRICULAR_GUIDELINES.md.

The OSSU computer-science repository hosts a free, open-source curriculum built as a static Jekyll site. Because the entire course structure lives in plain Markdown and configuration files, anyone can contribute to the OSSU computer science repository to fix broken links, update course descriptions, or propose new classes. This guide walks through the repository architecture, contribution workflows, and required standards for both minor edits and major curricular changes.

Understanding the Repository Architecture

The curriculum is organized as a Jekyll static site. Before you edit, recognize how the components map to file paths:

• _config.yml – Controls site-wide settings, base URL, and Markdown rendering options.
• coursepages/*/README.md – Contains individual course definitions organized by category (intro-cs/, core-cs/, advanced-cs/). Each file uses Markdown tables to list courses with columns for duration, effort, prerequisites, and Discord links.
• _includes/nav-items.html – Defines the navigation menu order.
• _layouts/page.html – The core Jekyll HTML template used to render all pages.
• extras/ – Supplementary resources such as additional readings, puzzles, and extra courses.
• CURRICULAR_GUIDELINES.md – Formal standards that all curriculum changes must satisfy.
• .github/workflows/delete-empty-issues.yml – A GitHub Actions workflow that automatically cleans up empty issues to keep the tracker tidy.

Contribution Workflow

The project follows a standard GitHub fork-and-pull workflow. To contribute to the OSSU computer science repository, complete these steps:

1. Fork the repository to your personal GitHub account.
2. Clone your fork locally.
3. Create a new branch for your changes (git checkout -b my-fix).
4. Edit the relevant Markdown or configuration files.
5. Commit with a clear message (git commit -m "Fix typo in Core CS description").
6. Push the branch to your fork.
7. Open a Pull Request (PR) against ossu/computer-science:master.

Maintainers review PRs for alignment with curricular guidelines and either merge or request changes.

Types of Contributions

Non-Substantive Edits

Minor corrections can be submitted directly via pull request without opening an issue first. These include:

• Fixing typos in course descriptions.
• Updating broken URLs in coursepages/*/README.md.
• Correcting outdated links in extras/ or the main README.md.

Substantive Edits

Changes that affect curriculum flow or content standards require an accompanying issue that outlines the problem, proposed solution, and alignment with the Curricular Guidelines. Substantive edits include:

• Adding or removing courses from any track.
• Changing prerequisite chains.
• Modifying the navigation structure in _includes/nav-items.html or _config.yml.

Adding a New Course: Practical Example

The following example demonstrates adding a new course to the Core Math section. The process applies to any category within coursepages/.

# 1. Fork the repo on GitHub (via the UI)

# 2. Clone your fork locally

git clone https://github.com/<your-username>/computer-science.git
cd computer-science

# 3. Create a new branch

git checkout -b add-discrete-math-course

# 4. Edit the Core Math README

#    (the file is at coursepages/core-math/README.md)

#    Append a new row to the Markdown table:

#    | [Discrete Math (MIT OpenCourseWare)](https://ocw.mit.edu/courses/6-042j-mathematics-for-computer-science-fall-2010/) | 12 weeks | 6-10 h/week | none | [chat](https://discord.gg/example) |

# 5. Stage, commit, and push

git add coursepages/core-math/README.md
git commit -m "Add MIT OCW Discrete Math to Core Math section"
git push origin add-discrete-math-course

# 6. Open a Pull Request on GitHub:

#    - Base repository: ossu/computer-science

#    - Base branch: master

#    - Compare: your new branch

#    - Fill PR description with justification and link to any supporting issue.

Key Files for Contributors

File	Purpose
README.md	Main landing page outlining the full curriculum structure.
CONTRIBUTING.md	Comprehensive contribution policy, issue/PR workflow, and style guidelines.
CURRICULAR_GUIDELINES.md	Mandatory standards for course quality, prerequisites, and academic rigor.
HELP.md	FAQ and troubleshooting guide for new contributors.
FAQ.md	Answers to common community questions about the curriculum.
coursepages/core-math/README.md	Example course category file where you add new table rows for math prerequisites.
.github/workflows/delete-empty-issues.yml	CI automation that maintains issue tracker hygiene.

Summary

• The OSSU curriculum is a Jekyll site where content lives in README.md files under coursepages/.
• Non-substantive changes (typos, links) can be submitted as direct PRs.
• Substantive changes (new courses, structure changes) require an issue and must align with CURRICULAR_GUIDELINES.md.
• Always branch from master, use clear commit messages, and target ossu/computer-science:master for your pull request.
• Navigation changes require editing _includes/nav-items.html or _config.yml.

Frequently Asked Questions

Do I need to know Jekyll or Ruby to contribute?

No. Most contributions involve editing Markdown files in coursepages/ or extras/. The Jekyll site builds automatically on GitHub Pages when changes are merged. You only need to understand basic Markdown table syntax to add or edit courses.

What is the difference between CONTRIBUTING.md and CURRICULAR_GUIDELINES.md?

CONTRIBUTING.md defines the procedural rules—how to open issues, branch naming conventions, and PR etiquette. CURRICULAR_GUIDELINES.md defines the academic standards—what constitutes a valid course, prerequisite logic, and workload requirements. Substantive changes must satisfy both documents.

How do I request a new course be added if I don't want to code?

Open a GitHub Issue describing the course, its URL, and how it meets the curricular guidelines. Reference the appropriate section in CURRICULAR_GUIDELINES.md and explain which prerequisite chain it fits into. Maintainers will triage the request and implement the change if approved.

Why was my pull request closed or asked for an accompanying issue?

If your PR changes course listings, adds new categories, or alters the flow of the curriculum, it is considered substantive. According to the workflow defined in CONTRIBUTING.md, these changes require a preceding issue to discuss alignment with academic standards before code review begins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}