Software Maintenance and Evolution

• Tally: 2 corrective, 2 preventive, 3 adaptive, 3 perfective.
• CR-02 and CR-03 are both faults. CR-02 was reported (reactive, corrective); CR-03 was found before any failure (proactive, preventive).
• CR-06 feels like a bug to the users, but the software did not change: the environment did. That makes it adaptive.
• CR-08 and CR-09 add functionality; the 2022 edition of the standard calls this additive, a kind of perfective enhancement.

• A legacy system is an older system that the organisation still depends on, but that is costly and risky to change.
• Typical signs: outdated language or platform, the original developers have left, little or no documentation, no automated tests, business rules that exist only in the code, data in formats nobody else reads.
• Michael Feathers (Working Effectively with Legacy Code, 2004) gives a practical definition: legacy code is code without tests. By that definition a two-month-old student project can already be legacy.
• Why not simply throw it away? It works, it encodes years of decisions, and a rewrite must reproduce all of that before it delivers any value.

First assess, then decide: rate each legacy system on business value and technical quality (after Sommerville, Software Engineering).

Rule of thumb: repay the items with the highest interest-to-principal ratio first, and items in code you are about to change anyway.

• Make it visible: one register row per item, linked from a // TD-03 comment in the code and a backlog item.
• Pay continuously: reserve a fixed share of each sprint (for example 15 to 20 %) instead of a "refactoring sprint" that never comes.
• Boy Scout rule: leave every file a little cleaner than you found it.

Names from Fowler, Refactoring, 2nd ed. (2018), except "magic numbers", a common name for a special case of Mysterious Name.

• A code smell is not a bug: the program works. It is a hint that the code will be expensive to change.
• Smells are judged in context: a 50-line function that reads like a recipe may be fine.
• Tools find many smells for you. The .clang-tidy file from Lab-09 can flag long and complex functions and magic numbers:

Checks: >
  readability-function-size,
  readability-function-cognitive-complexity,
  readability-magic-numbers
CheckOptions:
  - key: readability-function-size.LineThreshold
    value: 40
  - key: readability-function-cognitive-complexity.Threshold
    value: 15

// BEFORE: what is ok? what is t? why 24?
bool ok(const Event& e, TimePoint t) {
    return e.start - t >= std::chrono::hours{24};
}
// ...and in printReport(), the same expression three times:
double r = reg == 0 ? 0.0 : 100.0 * in / reg;

// AFTER 1: Rename Function, Rename Variable,
//          Replace Magic Literal with a named constant
constexpr auto kCancellationWindow = std::chrono::hours{24};

bool isCancellationOpen(const Event& event, TimePoint now) {
    return event.start - now >= kCancellationWindow;
}

// AFTER 2: Extract Function (one definition, three callers,
//          and now it can have its own unit test)
double attendanceRate(int checkedIn, int registered) {
    if (registered == 0) return 0.0;
    return 100.0 * checkedIn / registered;
}

# one refactoring = one commit, tests green each time
git commit -m "refactor: rename ok() to isCancellationOpen()"
git commit -m "refactor: add kCancellationWindow constant"
git commit -m "refactor: extract attendanceRate()"

// include/clubhub/Cli.hpp (after)
using Args = std::vector<std::string>;
using Handler = std::function<void(const Args&)>;

struct StudentEvent {
    std::string studentId;
    int eventId = 0;
};

class Cli {
public:
    Cli(RegistrationService& service, const EventRepository& events,
        std::ostream& out);
    void handleCommand(const std::string& line);

private:
    void list(const Args& args);
    void registerStudent(const Args& args);
    void cancel(const Args& args);
    void checkIn(const Args& args);
    void help(const Args& args);
    std::optional<StudentEvent> studentAndEvent(const Args& args,
                                                std::string_view usage);

    RegistrationService& service_;
    const EventRepository& events_;
    std::ostream& out_;
    std::unordered_map<std::string, Handler> commands_;
};

// src/Cli.cpp (after, excerpt)
Cli::Cli(RegistrationService& service, const EventRepository& events,
         std::ostream& out)
    : service_{service}, events_{events}, out_{out},
      commands_{
          {"list",     [this](const Args& a) { list(a); }},
          {"register", [this](const Args& a) { registerStudent(a); }},
          {"cancel",   [this](const Args& a) { cancel(a); }},
          {"checkin",  [this](const Args& a) { checkIn(a); }},
          {"help",     [this](const Args& a) { help(a); }},
      } {}

void Cli::handleCommand(const std::string& line) {
    const Args args = splitWords(line);
    const std::string cmd = args.empty() ? std::string{} : args[0];
    const auto it = commands_.find(cmd);
    if (it == commands_.end()) {
        out_ << "unknown command: " << cmd << '\n';
        return;
    }
    it->second(args);
}

void Cli::cancel(const Args& args) {
    const auto se = studentAndEvent(args, "cancel <student> <event>");
    if (!se) return;
    const Event event = events_.findById(se->eventId);
    if (!isCancellationOpen(event, Clock::now())) {
        out_ << "too late to cancel\n";
        return;
    }
    service_.cancel(se->studentId, se->eventId);
    out_ << "cancelled\n";
}

// include/clubhub/ReportGenerator.hpp
struct ClubStats {
    std::string clubName;
    int events = 0;
    int registrations = 0;
    int checkIns = 0;
};

struct MonthlyReport {
    std::chrono::year_month month;
    std::vector<ClubStats> clubs;
};

class ReportGenerator {
public:
    ReportGenerator(const EventRepository& events,
                    const RegistrationRepository& regs);
    MonthlyReport build(std::chrono::year_month m) const;
    void print(const MonthlyReport& r,
               std::ostream& out) const;
private:
    const EventRepository& events_;
    const RegistrationRepository& registrations_;
};

// include/clubhub/CsvEventRepository.hpp
class CsvEventRepository : public EventRepository {
    // ...
};

classDiagram
  direction LR
  class ReportGenerator {
    -events_ : EventRepository
    -registrations_ : RegistrationRepository
    +build(month) MonthlyReport
    +print(report, out) void
  }
  class EventRepository {
    <<interface>>
    +findAll() vector~Event~
  }
  class RegistrationRepository {
    <<interface>>
    +findByEvent(eventId) vector~Registration~
  }
  class CsvEventRepository
  class MonthlyReport {
    +month : year_month
  }
  class ClubStats {
    +clubName : string
    +events : int
    +registrations : int
    +checkIns : int
  }
  ReportGenerator --> EventRepository : reads
  ReportGenerator --> RegistrationRepository : reads
  ReportGenerator ..> MonthlyReport : creates
  MonthlyReport *-- "0..*" ClubStats : clubs
  EventRepository <|.. CsvEventRepository

Suppose Club Hub is at 1.3.2, a year after the course. Each change is judged on its own:

# CMakeLists.txt: the single source of the version number
cmake_minimum_required(VERSION 3.28)
project(clubhub VERSION 1.4.0 LANGUAGES CXX)

configure_file(include/clubhub/Version.hpp.in
               ${PROJECT_BINARY_DIR}/generated/clubhub/Version.hpp
               @ONLY)
target_include_directories(clubhub_core PUBLIC
                           ${PROJECT_BINARY_DIR}/generated)

// include/clubhub/Version.hpp.in
#pragma once
#include <string_view>

namespace clubhub {
inline constexpr std::string_view kVersion = "@PROJECT_VERSION@";
}

// src/main.cpp: clubhub --version  prints  clubhub 1.4.0
std::cout << "clubhub " << clubhub::kVersion << '\n';

stateDiagram-v2
  [*] --> Submitted
  Submitted --> Triaged: PO checks it is complete
  Triaged --> Analysed: impact analysis
  Analysed --> Approved: PO or CCB decides
  Analysed --> Rejected
  Analysed --> Deferred
  Deferred --> Analysed: next sprint planning
  Approved --> InProgress: in Sprint Backlog
  InProgress --> InReview: pull request
  InReview --> InProgress: changes requested
  InReview --> Done: merged, CI green
  Done --> Released: tag vX.Y.Z
  Released --> [*]
  Rejected --> [*]

CHANGE REQUEST CR-14                              Status: Approved
Title       Waiting list for full events
Requested   Robotics Club leader, week 12, after the Sprint 1 review
Category    Perfective (additive) · MoSCoW: Should
Problem     Popular events fill within minutes. When a student cancels,
            the seat stays empty because nobody knows it is free.
Proposal    When an event is full, "register" puts the student on a
            waiting list (first come, first served). A cancellation
            promotes the first waitlisted student to Registered.
Acceptance  Given a full event, when a student registers,
            then the status is Waitlisted and the position is shown.
Impact      See impact analysis IA-14: about 14 h, 5 classes, 9 tests
Size        M (5 story points) · Urgency: medium
Decision    Approved by the Product Owner for Sprint 2; target v0.2.0

• Who may approve? In Scrum the Product Owner orders the backlog; changes that affect other systems or the release date may need a change control board (CCB): here PO, Scrum Master and the instructor.
• Rejected and deferred requests are recorded with a reason, never silently dropped. The IT Project Management course covers integrated change control in depth.

Output of the analysis: the affected list, an estimate with its uncertainty, the risks, the version decision, and a recommendation (approve for Sprint 2) that goes back into CR-14.

%%{init: {'themeVariables': {'cScale0': '#3d8bfd', 'cScale1': '#20c997', 'cScale2': '#fd7e14', 'cScale3': '#6f42c1', 'cScaleLabel0': '#ffffff', 'cScaleLabel1': '#ffffff', 'cScaleLabel2': '#ffffff', 'cScaleLabel3': '#ffffff', 'fontSize': '16px'}}}%%
timeline
  title ITC Club Hub release line
  Week 10 : v0.1.0 Sprint 1 increment
  Week 12 : v0.2.0 waiting list and 24 h fix : listEvents(bool) deprecated
  Week 14 : v1.0.0 project submission : listEvents(bool) removed
  Next term : v1.0.x bug fixes only : v1.1.0 attendance CSV export

// v0.2.0: the old overload still works, but warns
[[deprecated("use listEvents(EventFilter); removed in 1.0.0")]]
std::vector<Event> listEvents(bool onlyUpcoming) const;

std::vector<Event> listEvents(const EventFilter& filter) const;

A caller now sees a compiler warning such as 'listEvents' is deprecated: use listEvents(EventFilter), with the version that removes it.

• Release management decides what goes into a release, builds and tests it from a baseline, versions and tags it, writes the notes, distributes it, and supports it afterwards.
• Cadence: time-based (every sprint, every term) or feature-based (when CR-14 is done). Student teams do best with time-based releases at the end of each sprint.
• Deprecation is how you remove something without surprising users: announce it (changelog, release notes), warn (compiler warning, runtime message), keep it working for at least one MINOR release, and remove it only in the next MAJOR release.
• Support window: say which versions still get fixes. For Club Hub after the course: only the latest 1.0.x.

# Changelog
All notable changes to ITC Club Hub are documented here.
The format is based on Keep a Changelog 1.1.0, and this
project adheres to Semantic Versioning.

## [Unreleased]

## [0.2.0] - 2026-11-20
### Added
- Waiting list for full events; a cancellation promotes
  the first waitlisted student (CR-14).
- `waitlist <event>` command shows the queue.
### Changed
- `handleCommand` uses a command map (no behaviour change).
### Deprecated
- `listEvents(bool)`: use `listEvents(EventFilter)`.
  Will be removed in 1.0.0.
### Fixed
- Cancelling exactly 24 h before the start was rejected
  (CR-13).

## [0.1.0] - 2026-11-06
### Added
- Register, cancel and check in from the command line.

Six section types: Added, Changed, Deprecated, Removed, Fixed, Security. Write the entry in the same pull request as the change, under Unreleased.

# .github/workflows/release.yml
name: release
on:
  push:
    tags: ['v*.*.*']
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Tag must match the CMake project version
        run: grep -q "VERSION ${GITHUB_REF_NAME#v}" CMakeLists.txt
      - run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
      - run: cmake --build build
      - run: ctest --test-dir build --output-on-failure
      - name: Release notes = this version's CHANGELOG section
        run: |
          awk -v v="${GITHUB_REF_NAME#v}" \
            '$0 ~ "^## \\[" v "\\]" {p=1; next} /^## \[/ {p=0} p' \
            CHANGELOG.md > notes.md
      - run: gh release create "$GITHUB_REF_NAME" --notes-file notes.md
        env:
          GH_TOKEN: ${{ github.token }}

$ lizard src/Cli.cpp                 # before
  NLOC    CCN   token  PARAM  length  location
    41     11    283      1      41 Cli::handleCommand@16-56@src/Cli.cpp
$ lizard src/Cli.cpp                 # after (largest function)
    10      3     88      1      10 Cli::handleCommand@71-80@src/Cli.cpp

• The maximum per function dropped from 11 to 3; the total grew slightly (16 over seven functions). Refactoring does not remove the decisions, it spreads them into small, named, separately testable pieces.
• A common threshold is CC ≤ 10 per function (McCabe's original advice); lizard warns above 15 by default.

# ITC Club Hub · Maintenance plan (v1.0, week 12)

## Scope and support
- Supported release: the latest 1.x; fixes ship as 1.x.PATCH.
- Compilers: GCC 13+, Clang 17+, MSVC 2022+ (C++20).
- Platforms: Windows 11, Ubuntu 24.04, macOS 14.

## Roles (after the course)
- Maintainer: the clubs office student assistant, named per term.
- Bugs: GitHub issue with the bug template; triage every Monday.
- Response: blocker 2 days · major 1 week · minor next release.

## Routine work
- Monthly: update the GoogleTest tag, run CI, read release notes.
- Each term: build with the newest lab compilers (adaptive work).
- 20 % of maintenance time goes to the technical-debt register.

## Effort and end of life
- ACT 20 % x 300 development hours = 60 h per year (5 h/month).
- Review every year; retire when the institute adopts a new system.

• ISO/IEC/IEEE 14764:2022 asks for a maintenance plan before delivery: scope of support, who maintains, resources, the process for requests, and how the handover works.
• Estimating effort with annual change traffic (Boehm, COCOMO, 1981): annual maintenance effort = ACT × development effort, where ACT is the fraction of the code expected to change each year.