Skip to content

Home

Jump to bottom
iqbal edited this page Aug 30, 2025 · 1 revision

Comprehensive Documentation

Index

Introduction

Welcome to the comprehensive documentation for this project. This document provides a detailed overview of the project, its structure, and how to contribute.

Project Structure

The project is organized into the following main directories:

.github

This directory contains GitHub-specific files, such as issue and pull request templates, as well as workflow definitions. The workflows are:

  • continuous-integration.yaml: Runs continuous integration checks on pull requests.
  • modify-assignments.yaml: Modifies assignments based on issue comments.
  • sync_content.yml: Syncs content from a remote source.

Courses Folder

This folder contains the omegaUp's Public Courses. The folers inside the Courses folder are named by their aliases. Each course-alias folder contains a course_settings.json file and a list of assignment-alias folders them each assignment contains a list of problem-alias folder in them, now each of the problem-alias is the extracted zip of the actual problem which we download from omegaup.com.

📁 Courses/
├── 📁 course-1-alias/
│   ├── 📄 course_settings.json
│   └── 📁 assignment-1-alias/
│       └── 📁 problem-1-alias/
│           ├── 📄 settings.json
│           ├── 📄 settings.distrib.json
│           └── 📁 statements/
│               └── 📄 es.markdown

Utils Folder

This directory contains utility scripts for managing the courses. The most important scripts are:

  • container.py: Manages containerized environments for running and testing code.
  • download_and_sync_courses.py: Downloads and syncs course materials from a remote source.
  • generateresources.py: Generates static resources for the courses.
  • lint: A script for linting the course materials.
  • problems.py: A script for managing problems within the courses.
  • runtests.py: Runs tests for the course materials.
  • update_assignment_problems.py: Updates the problems in a specific assignment.
  • upload.py: Uploads course materials to a remote server.
  • validate_content.py: Validates the content of the course materials.

problems.json

This is a autogenerated file contains a list of all the problems in the courses. Each problem is represented by an object with a path key, which specifies the path to the problem's directory. This file is used by the utility scripts to manage the problems in the courses.

sync-course.json

This file is used to request a synchronization of a course with the omegaup.com platform. To request a sync, you need to add an object to the requests array with your OmegaUp username, your GitHub username, and the pull request number of your sync request.

Getting Started

To get started with this project, you will need to have the following prerequisites installed:

  • Python 3
  • Pip
  • Git

Once you have the prerequisites installed, you can clone the repository and install the dependencies:

git clone https://github.com/omegaup/public-courses.git
cd public-courses
pip install -r utils/requirements.txt

Syncing Content from omegaup.com to this repository

The github actions are configured to push the latest content whenever some changes are pushed in the sync-course branch only

For Admin: If a admin want to sync the content from omegaup.com to course github repo, they can run the following commands:

  1. Checkout to the branch sync-course:
git checkout sync-course
  1. Reset the branch with the main branch:
git reset --hard origin/main
  1. Push the changes
git push --force

This will push the changes to sync-course branch, now the github action Sync Course Content will run which will add a commit made by the Github Actions bot with the latest content from omegaup.com.

For Contributors: If a contributor want to request syncing of content from the omegaup.com to the course repo in the github, they can raise a pr to targetting the sync-course branch with the changes in the sync-course.json file to keep a log of the sync request. Once the pr gets merged the sync-courses branch will have the a commit made by Github Actions bot containg the latest content from omegaup.com.

Modifying existing Problems Content

For Admin: If you want to modify the content of an existing problem in the course (eg: typo fixes, test case addition etc), you can change do the respected changes in the problem folder in the course's assignment folder and push the changes to the main branch.

For Contributors: If you want to request a change in the content of an existing problem in the course (eg: typo fixes, test case addition etc), you can raise a pull request with the changes to the main branch.

Adding or removing problems to the Couse:

The github actions are configured to add/remove the problems from the course on omegaup.com only when changes are pushed to the modify-assignments branch.

IMPORTANT - If you want to add a problem to the course and you want to have the problem contents to be in the repective course's assignment folder in the github repo as well then admin permissions need to be provided for that problem for the user - CourseBot

For Admin: If a admin wants to add/remove problem from the course they should do the following step:

  1. Checkout to the branch modify-assignments:
git checkout modify-assignments
  1. Reset the branch with the main branch:
git reset --hard origin/main
  1. Update the adding_removing_problems.json by adding the details of the problems, eg:
{
    "add_problem":[
        {
            "course_alias": "omi-public-course",
            "assignment_alias": "intro",
            "problem_alias": "demo-de-objetivo",
            "points": 100
        }
    ],
    "remove_problem":[
            "course_alias": "omi-public-course",
            "assignment_alias": "practice",
            "problem_alias": "Contest-Start",
        }
    ]
}
  1. Commit and push the changes:
git push --force

This will push the changes to modify-assignments branch, now the github action Modify Course Assignments will go through the adding_removing_problems.json in order to know what problems to add/remove:

  • If a problem is added and the admin permissions are provided for the problem to the CourseBot user then the problem zip file will be downloaded for the problem and will be extracted and added the respective course's assignment folder.
  • If a problem is removed then if the problem folder is present in the course's assignment folder in the github repo then it will be removed as well.
  • In both cases a commit will be added by the Github Bot, which would do the aforesaid changes.

For Contributors: If a contributor wants to request a problem to be added or removed then they can populate the modify-assignments accordingly, eg:

{
    "add_problem":[
        {
            "course_alias": "omi-public-course",
            "assignment_alias": "intro",
            "problem_alias": "demo-de-objetivo",
            "points": 100
        }
    ],
    "remove_problem":[
            "course_alias": "omi-public-course",
            "assignment_alias": "practice",
            "problem_alias": "Contest-Start",
        }
    ]
}

and raise a pull request targeting modify-assignments branch. When this pull request gets merged then the Github Actions Bot will add a commit to the branch for the desired changes.

Clone this wiki locally