Skip to content

Recitation 3: Software Archaeology - TA Guide

TBD: opencode migration

This TA guide is written against the NodeBB codebase (fork repo, issue links, feature specifics below). Needs a full rewrite against opencode before this recitation runs again.

Overview

This recitation introduces students to software archaeology - the practice of understanding and navigating unfamiliar codebases. Students will work hands-on with the NodeBB codebase to implement a username suggestion feature when registration fails due to duplicate usernames.

Learning Objectives

By the end of this recitation, students should be able to: - Navigate and understand the structure of a large, unfamiliar codebase - Use search tools and IDE features to locate relevant code sections - Differentiate between frontend and backend code - Implement small features by extending existing functionality - Understand the importance of software archaeology skills in professional development

Preparation (Before Recitation)

Required Materials

Setup Check

  • Ensure all students have access to the repository
  • Test that the NodeBB instance runs properly in the dev environment
  • Verify that students can fork and clone repositories

Recitation Timeline (50 minutes)

Introduction (10 minutes)

  1. Welcome & Context Setting (3 min)
  2. Explain software archaeology concept
  3. Real-world relevance: Most developers spend significant time reading existing code

  4. Today's goal: Learn systematic approach to understanding unfamiliar code

  5. Feature Overview (4 min)

  6. Show current NodeBB registration behavior
  7. Demonstrate the "username already exists" error

  8. Explain desired feature: suggest alternative usernames

  9. Task Overview (3 min)

  10. Walk through the GitHub issue
  11. Emphasize this is about process not just implementation
  12. Remind about PR requirement

Guided Exploration (15 minutes)

  1. Repository Structure Tour (8 min)
  2. Navigate through key directories together
  3. Point out src/ (backend) vs public/ (frontend)
  4. Highlight important files: package.json, README.md, etc.

  5. Show how to use IDE's file explorer effectively

  6. Search Strategies Demo (7 min)

  7. Demonstrate different search approaches:
    • Searching for error messages
    • Searching for "username" or "register" keywords
    • Using IDE's "Go to Definition" features
  8. Show how to filter search results
  9. Demonstrate git grep vs IDE search

Hands-on Work (20 minutes)

  1. Task 0: Repository Setup (5 min)
  2. Students fork and clone repository
  3. Follow README setup instructions
  4. Verify NodeBB runs locally

  5. TA Action: Circulate to help with setup issues

  6. Task 1: Reproduce Behavior (5 min)

  7. Students test current registration flow
  8. Try registering with existing username
  9. Document current error behavior

  10. TA Action: Ensure all students see the error message

  11. Task 2: Code Investigation (10 min)

  12. Students search for relevant code sections
  13. Identify whether changes needed in frontend/backend
  14. Locate error message sources
  15. TA Action: Guide students who are stuck, ask probing questions

Implementation & Wrap-up (5 minutes)

  1. Implementation Guidance (3 min)
  2. Brief discussion of findings as a group
  3. Hint at general approach without giving away solution

  4. Remind about i18n complexity (English only for this task)

  5. Next Steps (2 min)

    • Explain they should complete implementation after recitation
    • Review PR requirements
    • Mention optional advanced task
    • Preview next recitation

Common Code Locations (Spoiler-Free Hints)

Use these only if students are completely stuck after 10+ minutes of searching

  • User registration logic: Look in src/controllers/ or src/user/ directories
  • Client-side forms: Check public/src/client/ areas
  • Error message handling: Search for the specific error text
  • API endpoints: Look for routes that handle user creation

Locate the files to change

Help students find the relevant files using these search strategies:

Run grep -r "Username taken" in the public folder. This returns all files containing the string "Username taken" and will list several JavaScript files.

Step 2: Follow the Breadcrumbs

The files from Step 1 don't contain the actual implementation code. Instead, they reference a placeholder string called "username-taken".

Step 3: Search for the Placeholder

Run grep -r "username-taken" in the public folder. This returns many files, most of which are translation-related.

Step 4: Filter Out Translation Files

Run grep -r "username-taken" --exclude-dir=language to exclude translation files. This should return a single target file: src/client/register.js, which needs to be modified.

Make a string template

The goal is to change the error message from 'Account taken' to 'Account taken. Maybe try ${currentUsername}suffix'. This requires converting a static error message into a dynamic template.

Understanding Message Templates

Guide students to examine existing templated error messages in public/language/en-US/error.json. Look for examples like: 

'wrong-parameter-type': 'A value of type %3 was expected for property \%1`, but %2 was received instead'

This format shows how the project uses message templates with placeholder variables (%1, %2, %3).

Implementation Steps

  1. Modify the error message: In public/language/en-US/error.json, find line 34: 

    "username-taken": "Username taken",

  2. Add template placeholder: Change it to: 

    "username-taken": "Username taken. Maybe try %1",

  3. Update the error call: In src/client/register.js, modify the showError call from: 

    [[error:username-taken]]
    to: 
    [[error:username-taken, "${username}suffix"]]

How It Works

The %1 placeholder takes the value from the second argument passed to the showError function. When calling showError(username_notify, [[error:username-taken, "${username}suffix"]]), the ${currentUsername}suffix gets passed as the second argument and replaces %1 in the template.

Remember: The goal is teaching software archaeology skills, not just completing the feature. Focus on the process and investigation techniques that will serve students throughout their careers.