The Project Ecosystem

Before writing a single line of code, you need to understand the three spaces where the project lives and how they connect. Skipping this leads to the most common confusion: “I coded it, why does my grade not show it?”

Three spaces

flowchart LR
    subgraph CL["🎓 GitHub Classroom"]
        CL1["Invitation link<br/>Join / create team"]
        GH3["Teacher triggers<br/>evaluation (CI)"]
    end
    subgraph GH["☁️ GitHub Repository — github.com/Estia-1a/your-team"]

        GH2["Issues & milestones"]
        
        GH1["Source code & branches"]
    end
    subgraph M1["💻 Student 1's Machine (Team Leader)"]
        LM1["VS Code · gcc · CMake · Libraries"]
    end
    subgraph M2["💻 Student 2's Machine"]
        LM2["VS Code · gcc · CMake · Libraries"]
    end
    subgraph M3["💻 Student 3's Machine"]
        LM3["VS Code · gcc · CMake · Libraries"]
    end

    CL1 -->|"creates"| GH
    LM1 <-->|"git push / pull"| GH1
    LM2 <-->|"git push / pull"| GH1
    LM3 <-->|"git push / pull"| GH1
    GH3 -.->|"reads main branch"| GH1

GitHub Classroom

GitHub Classroom is the entry point. The teacher creates an assignment; you receive an invitation link. When you join and create or select your team, Classroom automatically creates a private GitHub repository for your team under the Estia-1a organization.

You interact with Classroom exactly once — during team registration. After that, everything happens either in the GitHub repository or on your local machine.

Your GitHub repository

Your team’s repository is the shared source of truth. It holds:

  • Your source code (in src/)
  • Issues that describe every feature to implement
  • GitHub Actions that compile and test your main branch every day
Important

Pushing code is not optional. Your grade is based on what is in the main branch on GitHub — not on your hard drive. If you do not push, your work does not exist for your teammates or the evaluator.

Your local machine

Your local machine is where you write and compile code. It needs three things installed and working:

What Role
VS Code Editor — where you write code
gcc + CMake Compiler and build system — turn your C into an executable
estia-image + getopt Prebuilt libraries — downloaded separately, not in the repository

Changes you make locally are invisible to your team and the evaluator until you commit and push them.

The heartbeat: edit → build → push

Every working session follows this cycle:

sequenceDiagram
    participant LM as Your Machine
    participant GH as GitHub (shared)

    LM->>LM: Edit code in VS Code
    LM->>LM: cmake --build build
    LM->>LM: ./freud.exe ... (test locally)
    LM->>GH: git commit + push
    Note over GH: Code now visible to teammates<br/>and available for evaluation
    GH->>LM: teammates: git pull

The cycle starts again on each edit. Never end a session without pushing.

Note

When is the code evaluated? The teacher triggers evaluation via GitHub Classroom on a schedule (daily). Your push makes the code available — the CI run happens on the teacher’s timeline, not immediately on push.

The onboarding flow

sequenceDiagram
    participant S1 as Student 1<br/>(Team Leader)
    participant S2 as Student 2
    participant S3 as Student 3
    participant GH as GitHub

    Note over S1,GH: Phase 1 — Register team on GitHub Classroom
    S1->>GH: Create team
    S2->>GH: Join team
    S3->>GH: Join team
    GH-->>S1: Repository created
    GH-->>S2: Repository created
    GH-->>S3: Repository created

    Note over S1,S3: Phases 2–4 — Each on their own machine (can work in parallel)
    par S1 sets up their machine
        S1->>S1: Clone · Install VS Code extensions
        S1->>S1: Download libraries
        S1->>S1: validconfig.sh → fix → build helloworld ✓
    and S2 sets up their machine
        S2->>S2: Clone · Install VS Code extensions
        S2->>S2: Download libraries
        S2->>S2: validconfig.sh → fix → build helloworld ✓
    and S3 sets up their machine
        S3->>S3: Clone · Install VS Code extensions
        S3->>S3: Download libraries
        S3->>S3: validconfig.sh → fix → build helloworld ✓
    end

    Note over S1,GH: Phase 5 — Activate workflows (team leader only)
    S1->>GH: validconfig.sh --activate-workflows
    Note over S2,S3: Wait for leader to confirm push
    GH->>S2: git pull
    GH->>S3: git pull

    Note over S1,GH: Phase 6 — Import issues (one person)
    S1->>GH: Actions → Import issues from Template
    GH-->>GH: Issues created
    GH->>S2: git pull
    GH->>S3: git pull

    Note over S1,S3: ✅ Setup complete — go to First Steps

Ready to begin? Go to Setup.