Lab-01: Software Development Challenges

1. Tools (every member). Git, a GitHub account that shows your real name, a C++20 compiler (GCC 13, Clang 17 or Visual Studio 2022 or later) and CMake 3.28 or later. An editor: VS Code with the C/C++ extension, CLion or Visual Studio. Check the versions and set your Git identity to the e-mail address verified on GitHub, otherwise your commits will not be linked to your account.

   git --version          # 2.40 or later
   cmake --version        # 3.28 or later
   g++ --version          # GCC 13+ (or: clang++ --version, or cl in a VS Developer prompt)
   git config --global user.name  "Chan Dara"
   git config --global user.email "dara@example.edu"   # the e-mail verified on GitHub

2. Team. Form a team of 4 to 5 students (or use the instructor's list). Sit together, in person or on a call, for Tasks 1 and 4.
3. Inputs. Lab-01 is the first lab, so there are no earlier deliverables. It uses only the inputs below and produces the inputs that every later lab reuses (team charter, repository, problem statement, stakeholders, the clubhub build).

   Input	Where	What you need from it	Fallback if missing
   Team list	Instructor, first class	Who is in your team	Form a team of 4 to 5 yourselves and tell the teaching assistant (TA) before the end of the class.
   Product definition	Case-study brief (next step)	Users, features, business rules, personal data, rhythm, roles	Always available; it is the product definition for this course.
   Failure-case list	Task 3	The case your team analyses	If the instructor has not assigned one, pick one from the list and tell the TA, so that neighbouring teams differ.
   Chapter 01 slides	Chapter 01	Essential difficulties, n(n-1)/2, cost of change, technical debt, roles, team charter example	None needed.

4. Case-study brief. The box below is the complete product definition for this lab; wherever a step says "the case-study brief", it means this box.
   Case-study brief: ITC Club Hub

   Purpose

   An application for the student clubs of the Institute of Technology of Cambodia (ITC): clubs publish events, students register for them, organisers check attendance and administrators see what happens across clubs.

   Users and roles

   Student: browses events, registers, cancels, receives a reminder. Club leader: registers a club and publishes its events. Organiser: checks registered students in at the door and sees attendance. Administrator: approves clubs and sees a monthly activity report across clubs.

   Main features

   Club registration and approval · events with title, date and time, location, capacity and description · browse, register and cancel · reminders · check-in and attendance · monthly activity report.

   Business rules

   Capacity cannot be exceeded (a waiting list is a Should feature) · a student cannot register twice for the same event · cancellation closes 24 hours before the start · events in the past cannot be registered for · only approved clubs can publish events.

   Personal data

   Student ID, name, e-mail, phone (optional), club membership, attendance records.

   What you build

   Analyse and model the full system as a web and mobile application; implement its core in C++20: the domain model, the business rules and a command-line front end, with CSV or JSON file storage. Code in namespace clubhub; layout CMakeLists.txt, src/, include/clubhub/, later tests/ and .github/workflows/ci.yml.

   Team roles

   One Product Owner who liaises with the client (the instructor or a TA plays the client), a Scrum Master who rotates each sprint, the other members Developers. Everyone writes code.

   Rhythm

   15-week semester: one lab per week in one team repository (lab01/ … lab11/) · midterm in week 8 · Sprint 1 in weeks 9 and 10 · Sprint 2 in weeks 11 and 12 · project submission and demo in week 14 · final exam in week 15.

5. Deliverables of this lab. By the end, your repository looks like this (branch lab-01):

   clubhub-<team-name>/
   ├── README.md                       # Task 2 (team table, layout, build command)
   ├── .gitignore                      # Task 2 (C++ / CMake)
   ├── LICENSE                         # Task 2 (placeholder until Lab-03)
   ├── CMakeLists.txt                  # Task 5
   ├── include/clubhub/banner.hpp      # Task 5
   ├── src/banner.cpp                  # Task 5
   ├── src/main.cpp                    # Task 5
   └── lab01/
       ├── team-charter.md             # Task 1
       ├── decisions.md                # Task 1 (decision log)
       ├── failure-case-analysis.md    # Task 3
       ├── problem-statement.md        # Task 4
       ├── stakeholders.md             # Task 4
       ├── failure-risks.md            # Task 4
       ├── README.md                   # Task 5 (Record what changed)
       └── communication-overhead.md   # Challenge

6. Conventions. Every Markdown file starts with a title, a version (v0.1, v1.0) and a date. Commit messages start with the lab and task: Lab-01 task 3: root causes. Commit your own work from your own account; when two people wrote something together, add a Co-authored-by: Name <email> line to the commit message.

Goal

Agree, in writing, who is in the team, which role each member plays, how you work together, which channels you use and how you decide. The charter answers now the questions that otherwise cause conflict in week 10.

Steps

1. Choose a facilitator (keeps time, makes sure everyone speaks) and a scribe (writes the file). Choose a short team name without special characters; it appears in the repository name (Task 2) and in the program banner (Task 5).
2. Create lab01/team-charter.md from the starter (write it in a shared editor for now; Task 2 commits it). Fill Members and roles: full name, GitHub username, role for Sprint 1 (exactly one Product Owner, one Scrum Master, the rest Developers) and one shared hat per member from the Chapter 01 roles (business analyst, UX designer, tester, DevOps engineer). Do not write student IDs or phone numbers in the repository.
3. Write the Scrum Master rotation for Sprint 1 and Sprint 2 (two different people) and state that the Product Owner stays the same all semester.
4. Write at least five working agreements that someone could check: a time, a number or an observable action ("every pull request is reviewed by one other member within 24 hours on weekdays", not "we communicate well").
5. Fill Communication channels: which channel for chat, for work items (GitHub Issues), for files (the repository) and for meetings, with the expected response time.
6. Fill Decision rules for product questions, technical questions and deadlocks, and create lab01/decisions.md with its first entry: the team name decision (date, decision, who decided, alternatives).
7. Leave the Agreed by list empty: in Task 2 each member adds their own name in their own commit.

Starter template

# Team charter · <team name> (v1.0, 2026-__-__)

## Members and roles
| Member | GitHub | Role (Sprint 1) | Shared hat |
|--------|--------|-----------------|------------|
|        | @      | Product Owner   |            |
|        | @      | Scrum Master    |            |
|        | @      | Developer       |            |

Scrum Master rotation: Sprint 1 = ______, Sprint 2 = ______.
The Product Owner stays the same all semester.

## Working agreements
1. TODO (checkable: a time, a number or an observable action)
2. ...

## Communication channels
| Purpose       | Channel          | Expected response |
|---------------|------------------|-------------------|
| Chat          |                  |                   |
| Work items    | GitHub Issues    |                   |
| Files         | this repository  | n/a               |
| Meetings      |                  |                   |

## Decision rules
- Product questions:
- Technical questions:
- Deadlock (no agreement after __ hours):
- Where decisions are recorded: lab01/decisions.md

## Agreed by
<!-- each member adds "- Name, date" in their own commit (Task 2) -->

# Decision log · <team name> (v0.1, 2026-__-__)
| # | Date | Decision | Decided by | Alternatives considered |
|---|------|----------|------------|-------------------------|
| 1 |      | Team name "..." | vote 4-1 | ... |

Expected output (excerpt of team-charter.md)

Members and roles: 5 rows, 1 Product Owner (Chan Dara), 1 Scrum Master
  (Sok Sokha), 3 Developers; hats: business analysis, testing x2,
  DevOps (build, CI), UX sketches.
Scrum Master rotation: Sprint 1 = Sok Sokha, Sprint 2 = Keo Malis.
Working agreements (6), e.g.
  3. Every pull request is reviewed by one other member within 24 h
     (Mon-Fri); the author merges after approval.
  5. Anyone blocked for more than 2 hours posts in the chat.
Decision rules: product -> PO decides after hearing everyone;
  technical -> consensus within 24 h, else majority vote;
  deadlock -> ask the TA at the next lab session.

Show hints

Acceptance checklist

Goal

Create the one repository the team uses all semester, with the agreed layout, and prove that every member can push: each member makes at least one commit from their own account.

Steps

1. The DevOps-hat member creates an empty GitHub repository named clubhub-<team-name> (lowercase, hyphens), with the visibility the instructor asks for, and invites the other members (role Write) and the TA. Leave branch protection off for now; it is switched on when the CI pipeline exists (Chapter 08).
2. Clone it and create the skeleton on main: README.md and .gitignore from the starters, a LICENSE file containing only the placeholder line All rights reserved until the team chooses a licence (Lab-03)., and an empty lab01/.gitkeep. Commit Lab-01 task 2: repository skeleton and push.
3. Create the lab branch that will carry all remaining Lab-01 work: git switch -c lab-01 then git push -u origin lab-01.
4. The scribe of Task 1 adds lab01/team-charter.md and lab01/decisions.md on lab-01, commits and pushes.
5. Every other member clones, runs git switch lab-01 and git pull --rebase, adds their own row to the Team table in README.md and their own line under Agreed by in team-charter.md, then commits and pushes from their own account. One member at a time, or pull again before pushing.
6. Check the history: git shortlog -sn --all lists every member, and on GitHub each commit shows the member's avatar (the e-mail matches their account).

Starter files

# .gitignore for a C++ / CMake project
# build output
build/
out/
cmake-build-*/
CMakeCache.txt
CMakeFiles/
cmake_install.cmake
compile_commands.json
Testing/
# compiled files
*.o
*.obj
*.a
*.lib
*.so
*.dll
*.exe
*.pdb
# editors and operating systems
.vs/
.idea/
*.swp
.DS_Store
Thumbs.db

# ITC Club Hub · Team <team name>

An application for the student clubs of the Institute of Technology of
Cambodia. Course project, Introduction to Software Engineering.

## Team
| Member | GitHub | Role (Sprint 1) |
|--------|--------|-----------------|
<!-- each member adds their own row in their own commit -->

## Repository layout
| Path | Content |
|------|---------|
| `lab01/` ... `lab11/` | Documents of each lab |
| `include/clubhub/`    | Public C++ headers (namespace clubhub) |
| `src/`                | C++ sources |
| `tests/`              | Unit tests (added in a later lab) |

## Build
    cmake -S . -B build
    cmake --build build

Expected output

$ git shortlog -sn --all
     3  Heng Vanna
     2  Sok Sokha
     1  Chan Dara
     1  Keo Malis
     1  Lim Piseth

$ git log --oneline --graph --all
* 5c1e9a2 (HEAD -> lab-01, origin/lab-01) Lab-01 task 2: add Lim Piseth to team
* 91b0d4f Lab-01 task 2: add Keo Malis to team
* 7d22e8c Lab-01 task 2: add Chan Dara to team
* 3f0c6b1 Lab-01 task 2: add Sok Sokha to team
* e8a41d7 Lab-01 task 1: team charter and decision log
* 2a7f310 (origin/main, main) Lab-01 task 2: repository skeleton

Show hints

Acceptance checklist

Goal

Analyse one real software failure with a structured template: context, what failed, root causes mapped to Brooks's essential difficulties, and the practices that would have prevented it. You will meet those practices again in later chapters.

Case list (the instructor assigns one per team so that neighbouring teams differ; Ariane 5 is the worked example of the slides and is not on the list):

• Therac-25 radiation therapy machine, 1985-1987
• Mars Climate Orbiter, lost in 1999
• Northeast blackout (United States and Canada), 2003
• Knight Capital trading loss, 2012
• Post Office Horizon accounting system (United Kingdom), 1999 onwards
• Boeing 737 MAX MCAS, 2018-2019
• CrowdStrike Windows outage, 2024

Steps

1. Split the sections of lab01/failure-case-analysis.md among the members; each member commits the section they wrote. Collect at least three sources, at least one of them primary (official inquiry report, regulator, or the organisation's own post-incident review), and list them under Sources.
2. Write Context (organisation, system, users, why it mattered) and a Timeline of 5 to 8 dated events. Keep to facts reported by the sources; no speculation.
3. Write What failed: one paragraph on the technical failure, plus the causal chain as a Mermaid flowchart TD with at least five nodes, from the first root cause to the final impact (like the Ariane 5 chain on slide 19).
4. Fill the Root causes table with at least three causes. For each: type (technical, process or organisational), the essential difficulty it shows (complexity, conformity, changeability, invisibility) or accidental, and a one-sentence justification.
5. Fill Practices: for every root cause at least one engineering practice that would have prevented or limited the damage, and the chapter of this course that covers it (for example "staged rollout, Chapter 08", "acceptance tests for units, Chapter 09").
6. Write two concrete Lessons for ITC Club Hub ("our CSV import rejects a capacity that is not a whole number between 1 and 500", not "we will be careful").

Starter template

# Failure case analysis · <case> (v1.0, 2026-__-__)
Authors: <member per section>

## 1. Context
## 2. Timeline
| Date | Event |
|------|-------|

## 3. What failed
<one paragraph>

```mermaid
flowchart TD
  A["root cause"] --> B["..."]
  B --> C["..."]
  C --> D["..."]
  D --> E["impact"]
```

## 4. Root causes
| # | Root cause | Type | Essential difficulty | Why |
|---|------------|------|----------------------|-----|
| R1 |           | technical / process / organisational | | |

## 5. Practices that would have prevented or limited it
| Root cause | Practice | Chapter |
|------------|----------|---------|

## 6. Lessons for ITC Club Hub
1.
2.

## 7. Sources
1. <author or organisation, title, year, URL> (primary)

Expected output (format example with Ariane 5, taken from the slides)

flowchart TD
  A["Ariane 4 alignment code reused unchanged"] --> B["Ariane 5 trajectory: larger horizontal values"]
  B --> C["float to 16-bit integer conversion overflows"]
  C --> D["Unhandled exception: both inertial units stop"]
  D --> E["Diagnostic data read as flight data"]
  E --> F["Launcher breaks up, self-destructs"]

| R1 | Code reused from Ariane 4 without re-checking its assumptions
|    | against the Ariane 5 trajectory | process | changeability |
|    | the requirements changed, the code and its analysis did not |
| R2 | Conversion left unprotected to save processor time | technical |
|    | complexity | the safety argument depended on a value range
|    | nobody recorded as a requirement |
Practices: R1 -> re-validate reused components against new
requirements (Ch 05, Ch 10); R2 -> test with realistic flight data,
handle every conversion error (Ch 09).

Show hints

Acceptance checklist

Goal

Describe the problem ITC Club Hub solves on one page, list who has a stake in it, and name five things that could make this project fail, each linked to a Chapter 01 topic. These three files are the starting point of the requirements work in Chapter 05.

Steps

1. The Product Owner talks to the client (the TA) for 10 minutes, or works from the case-study brief if the client is not available, and notes three pains of today's club life (for example: sign-ups in chat groups, overcrowded rooms, no attendance record).
2. Write lab01/problem-statement.md (one page at most): the problem statement sentence, the product vision sentence, the current workaround, and a Scope section with three lists: built in C++ this semester, modelled only (web and mobile screens), out of scope.
3. Write lab01/stakeholders.md: a table with at least seven stakeholders or groups (students, club leaders, organisers, administrators, the client, the institute's IT staff, your team, and anyone else you find), each with interest, influence (high, medium, low), what they need from Club Hub and how you will reach them. Mark the three most important with ★.
4. Write lab01/failure-risks.md: five ways this project could fail. Link each to a different Chapter 01 topic (essential difficulties, scale and communication, changing requirements and cost of change, reliability, security and safety, legacy, integration and technical debt), and give an early warning sign, a first countermeasure and an owner (a team member).
5. The Product Owner commits the three files; one other member reviews them and commits at least one improvement (or leaves a review comment on the pull request) so that the review is visible.

Starter templates

# Problem statement · ITC Club Hub (v0.1, 2026-__-__)

## Problem
The problem of ____________________ affects ____________________;
the impact of which is ____________________.
A successful solution would ____________________.

## Vision
For ______ who ______, ITC Club Hub is a ______ that ______.
Unlike ______, our product ______.

## Today's workaround
## Scope
- Built in C++ this semester:
- Modelled only (web and mobile):
- Out of scope:

# Stakeholders · ITC Club Hub (v0.1, 2026-__-__)
| Stakeholder | Interest | Influence | Needs from Club Hub | How we reach them |
|-------------|----------|-----------|---------------------|-------------------|
| ★ Students  |          |           |                     |                   |

# Failure risks · ITC Club Hub (v0.1, 2026-__-__)
| # | How the project could fail | Chapter 01 topic | Early warning sign | First countermeasure | Owner |
|---|----------------------------|------------------|--------------------|----------------------|-------|
| F1 |                           |                  |                    |                      |       |

Expected output (excerpt of failure-risks.md)

F2 | Two developers implement "capacity" differently (seats vs.
   | registrations) and the rules drift apart
   | topic: essential difficulties (invisibility)
   | warning: the same rule appears in two places in the code
   | countermeasure: one function per business rule + a unit test;
   |   rules listed in the README | owner: Heng Vanna
F4 | Student e-mails and phone numbers leak through a CSV file
   |   pushed to a public repository
   | topic: reliability, security and safety
   | warning: real data files appear in `git status`
   | countermeasure: only invented test data in the repo; data/
   |   in .gitignore | owner: Sok Sokha

Show hints

Acceptance checklist

Goal

Create the CMake project that every later lab extends: a library clubhub_core for all code except main(), and an executable clubhub that prints a banner with the version and the team name. Then record what this lab produced in lab01/README.md.

Steps

1. Work as a pair: one driver types, one navigator reviews; swap after each file. Both appear in the history: the committer adds Co-authored-by: Name <email> for the partner.
2. Create CMakeLists.txt at the repository root from the starter: project clubhub version 0.1.0, C++20 required without compiler extensions, library clubhub_core with include/ as public include directory, executable clubhub linked to it, warnings on (/W4 or -Wall -Wextra -Wpedantic).
3. Create include/clubhub/banner.hpp from the starter and set kTeamName to your team name.
4. Implement clubhub::banner in src/banner.cpp: a rule of 40 = characters, the line ITC Club Hub v0.1.0 (the version comes from CMake through CLUBHUB_VERSION), the line Team: <name>, and the rule again, each line ending in '\n'. Create src/main.cpp from the starter.
5. Configure, build and run from the repository root. The build must finish with zero warnings, and git status must not show build/.
6. Record what changed: create lab01/README.md from the starter: the table of this lab's files (file, task, authors), the line Inputs reused from earlier labs: none (first lab), and the change-log row with date, version v0.1.0, summary and the commit hash of the last Lab-01 commit (git log -1 --format=%h; add it in a final small commit).
7. Push lab-01 and open the pull request described in Submission.

Starter code

# CMakeLists.txt
cmake_minimum_required(VERSION 3.28)
project(clubhub VERSION 0.1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# Library: all code except main(); later labs link tests to it
add_library(clubhub_core src/banner.cpp)
target_include_directories(clubhub_core PUBLIC include)
target_compile_definitions(clubhub_core
    PRIVATE CLUBHUB_VERSION="${PROJECT_VERSION}")
if(MSVC)
    target_compile_options(clubhub_core PRIVATE /W4)
else()
    target_compile_options(clubhub_core PRIVATE -Wall -Wextra -Wpedantic)
endif()

# Executable: the command-line front end
add_executable(clubhub src/main.cpp)
target_link_libraries(clubhub PRIVATE clubhub_core)

// include/clubhub/banner.hpp
#pragma once

#include <string>
#include <string_view>

namespace clubhub {

// The team name printed at start-up. TODO: your team name.
inline constexpr std::string_view kTeamName = "Angkor Coders";

// Returns the start-up banner, one line per row, ending in '\n'.
[[nodiscard]] std::string banner(std::string_view teamName);

}  // namespace clubhub

// src/banner.cpp
#include "clubhub/banner.hpp"

namespace clubhub {

std::string banner(std::string_view teamName) {
    const std::string rule(40, '=');
    std::string out;
    // TODO: rule, "  ITC Club Hub  v" CLUBHUB_VERSION, "  Team: " + teamName,
    //       rule; every line ends in '\n'
    (void)teamName;
    return out;
}

}  // namespace clubhub

// src/main.cpp
#include <iostream>

#include "clubhub/banner.hpp"

int main() {
    std::cout << clubhub::banner(clubhub::kTeamName);
    std::cout << "Commands arrive in a later lab. Bye!\n";
    return 0;
}

# Lab-01 · Software Development Challenges (v1.0, 2026-__-__)

## Files of this lab
| File | Task | Authors |
|------|------|---------|
| lab01/team-charter.md | 1 | |
| ... | | |
| CMakeLists.txt, include/clubhub/banner.hpp, src/*.cpp | 5 | |

Inputs reused from earlier labs: none (first lab).

## Change log
| Date | Version | Change | Commit |
|------|---------|--------|--------|
| 2026-__-__ | v0.1.0 | Team, repository, failure analysis, problem statement, first build | abc1234 |

Expected output

$ cmake -S . -B build
-- The CXX compiler identification is GNU 13.2.0
-- Configuring done
-- Generating done
$ cmake --build build
[ 50%] Built target clubhub_core
[100%] Built target clubhub
$ ./build/clubhub            # Visual Studio generator: build\Debug\clubhub.exe
========================================
  ITC Club Hub  v0.1.0
  Team: Angkor Coders
========================================
Commands arrive in a later lab. Bye!
$ git status --short        # nothing from build/ appears

Show hints

Acceptance checklist

1. Repository layout on branch lab-01:

   clubhub-<team-name>/
   ├── README.md
   ├── .gitignore
   ├── LICENSE                         # placeholder until Lab-03
   ├── CMakeLists.txt
   ├── include/clubhub/banner.hpp
   ├── src/banner.cpp  src/main.cpp
   └── lab01/
       ├── team-charter.md  decisions.md
       ├── failure-case-analysis.md
       ├── problem-statement.md  stakeholders.md  failure-risks.md
       ├── README.md                   # files, inputs reused, change log
       └── communication-overhead.md   # challenge

2. Self-check from a fresh clone in an empty folder; every command must succeed. ctest reports that no tests were found until tests are added in a later lab; that is expected.

   git clone https://github.com/<owner>/clubhub-<team-name>.git check
   cd check && git switch lab-01
   cmake -S . -B build && cmake --build build && ctest --test-dir build
   ./build/clubhub                 # Visual Studio generator: build\Debug\clubhub.exe
   git shortlog -sn                # every member appears
   git status --short              # empty: nothing from build/

3. Manual checklist: the Mermaid diagrams render on GitHub; every Markdown file has a title, a version and a date; lab01/README.md lists every file of this lab.
4. Open a pull request from lab-01 into main titled Lab-01 – <team name>. In the description list the members with their roles, the failure case you analysed and a link to lab01/README.md. Merge after the TA's feedback.