First Steps

The development loop

Before touching any feature code, internalize this cycle. Every working session repeats it:

flowchart LR
    E["✏️ Edit<br>VS Code"] --> B["🔨 Build<br>cmake --build build"]
    B --> R["▶️ Run<br>./freud.exe ..."]
    R --> C["📦 Commit<br>git commit -m '...'"]
    C --> P["🚀 Push<br>git push"]
    P --> PL["⬇️ Teammates pull<br>git pull"]
    PL --> E

The first time (or after changing CMakeLists.txt), also run configure and install:

cmake -B build           # configure — run once, or after CMakeLists changes
cmake --build build      # compile
cmake --install build    # install
./freud.exe --debug -f images/input/image.jpeg -c helloworld

Important

Always end a session with a push. GitHub Actions evaluate what is on main. Code that stays on your machine is invisible to your teammates and the evaluator.

---

Milestone 1 — Learn together (mob programming)

Milestone 1 is the Tutorial milestone. Its five issues are not distributed one per person — they are solved together, rotating who types at the keyboard.

Why mob programming for Milestone 1?

The goal is that everyone on the team understands:

• How the project compiles and runs
• How image data is structured in memory
• The exact pattern to add a new feature (header → implementation → manifest)
• How to commit and push

If one person solves all five issues alone, the others miss the learning. This will hurt everyone in the individual, closed-book final exam where no one can ask a teammate for help.

The rotation rhythm

sequenceDiagram
    participant S1 as Student 1 (keyboard)
    participant S2 as Student 2 (watching)
    participant S3 as Student 3 (watching)
    participant GH as GitHub

    Note over S1,S3: Everyone gathers at Student 1's screen
    Note over S1,S3: Read Issue #3 together — discuss the solution
    S1->>S1: Implement, build, run
    S1->>GH: git commit + push

    Note over S1,S3: Move to Student 2's screen
    S2->>GH: git pull
    Note over S1,S3: Read Issue #4 together — discuss the solution
    S2->>S2: Implement, build, run
    S2->>GH: git commit + push

    Note over S1,S3: Move to Student 3's screen
    S3->>GH: git pull
    Note over S1,S3: Read Issue #5 together — discuss the solution
    S3->>S3: Implement, build, run
    S3->>GH: git commit + push

    Note over S1,S3: Continue rotating for Issues #6 and #7

Rules:

• Everyone watches, everyone talks. The person at the keyboard types.
• Each student must commit and push at least once during Milestone 1.
• Do not split the five issues and work in parallel — that defeats the entire purpose of Milestone 1.

Milestone 1 issues (Tutorial)

#	Feature	What it teaches
#1	Dimension	Open an image, read width and height
#2	Color of the first pixel	Access pixel data, index into the array
#3	Color of the 10th pixel	Offset arithmetic in a pixel array
#4	First pixel, second line	2D indexing: row × width + column
#5	RGB pixel get and print	Reusable helper functions

---

Later milestones — Collaborative workflow

Once everyone understands the basics from Milestone 1, you can distribute effort across features. Distributing work does not mean working in isolation. Every feature starts with the whole team together.

Per-feature workflow

sequenceDiagram
    participant S1 as Student 1
    participant S2 as Student 2
    participant S3 as Student 3
    participant GH as GitHub

    Note over S1,S3: All gather — read the issue spec together<br/>Agree on function signature and expected output

    Note over S1,GH: One member writes the stub (example: Student 2)

    Note over S2, S2: Integrator prepare the workflow
    S2->>S2: Add signature of F1,F2, F3 to features.h
    S2->>S2: Add function call F1,F2, F3 in main.c<br/>(compiles but does nothing yet)
    S2->>S2: Add signature stubs in features.c<br/>( prepare space for implementation )
    S2->>GH: git commit + push
    GH->>S1: git pull
    GH->>S3: git pull

    Note over S1,S3: Now anyone can implement without conflicts

    Note over S1,GH: Example: Student 1 implements feature F1
    S1->>S1: Implement F1 in features.c
    S2->>S2: Implement F2 in features.c
    S3->>S3: Implement F3 in features.c 
    S1->>S1: Build · Run · Check output vs spec
    S1->>GH: git commit + push
    S2->>S2: Build · Run · Check output vs spec
    S2->>S2: git commit 
    GH->>S2: git pull
    S2->>GH: git push
    S3->>S3: Build · Run · Check output vs spec : Not working
    S3->>S3: Continue working
    S3->>S3: Build · Run · Check output vs spec
    S3->>GH: git commit
    GH->>S3: git pull
    S3->>S3: Resolve merge conflict (if any) — make sure main still builds
    S3->>GH: git push
    GH->>S1: git pull
    GH->>S2: git pull


    Note over S1,S3: Next feature → rotate who writes the stub

Why agree on the signature first? The function signature is the contract between teammates. Once it is committed and everyone has pulled, anyone can implement the body without causing merge conflicts. If you skip this step and two people modify features.h and features.c simultaneously, you will spend time resolving conflicts instead of coding.

For a deeper look at collaboration strategies — pair programming, integrator/coder roles, test-driven work — see Collaboration Strategies.

---

Where to code

The source code lives in the src/ folder. You can check Freud Internals for the file structure and where to add new code. You can update the source code architecture, but don’t forget to run cmake -B build to update the build system with your changes.