Change Log Workflow

Change Log Workflow

Use this workflow whenever the website is changed manually or through an AI-assisted task.

Goal

Keep two levels of documentation in sync:

  • A high-level index in docs/website-change-overview.md
  • A detailed task log in docs/logs/

This makes it easy to understand what changed, why it changed, how it was validated, and which files to edit next time.

Required Files

  • High-level index: docs/website-change-overview.md
  • Detailed logs folder: docs/logs/
  • Repo-specific AI rules: .github/copilot-instructions.md

Required Process For Every Change

  1. Create or update a detailed log in docs/logs/YYYY-MM-DD-short-topic.md.
  2. Record the request, context map, implementation plan, progress notes, validation, and closure in that detailed log.
  3. Add or update one row in docs/website-change-overview.md.
  4. In the overview row, list the main files to edit manually next time.
  5. If the workflow itself changed, update this file and .github/copilot-instructions.md.
  6. Before committing, confirm that .serena/ is not included.

Detailed Log Template

# Detailed Change Log: <Title>

Date: YYYY-MM-DD
Repository: <repo>
High-level entry: [website-change-overview.md](../website-change-overview.md)

## Request

## Context Map

### Files to Modify

| File | Purpose | Planned Change |
| --- | --- | --- |

### Risks

## Task Steps

## Implementation Plan

## Progress Updates

## Final Implementation Results

## Verification Notes

## Closure

Naming Convention

  • Detailed logs: docs/logs/YYYY-MM-DD-short-topic.md
  • Keep topic names short and stable.
  • Prefer one detailed log per user-facing change set.

Manual Editing Guide

Content updates

  • Biography and homepage narrative: _pages/about.md
  • CV content: _pages/cv.md, _data/cv.json
  • Publications: _publications/*.md
  • Talks: _talks/*.md
  • Teaching: _teaching/*.md
  • Main navigation: _data/navigation.yml
  • Masthead markup: _includes/masthead.html
  • Page layout wrappers: _layouts/, _includes/

Styling and behavior

  • Main JS behavior: assets/js/_main.js
  • Sass entrypoint: assets/css/main.scss
  • Layout styles: _sass/layout/*.scss

Validation Expectations

  • Rebuild JavaScript after JS changes: npm run build:js
  • Rebuild or restart Jekyll when needed, especially after config or Sass changes
  • Check the affected pages in the local preview
  • Note any remaining limitations in the detailed log