pages/MAINTENANCE.md

Maintenance & Updates Guide

This guide helps you maintain your al-folio website and keep it up-to-date with the latest features and security patches.

• Maintenance & Updates Guide
  • Overview
  • Dependency Management
    • Understanding Dependencies
    • Checking for Updates
    • Updating Gems (Ruby)
    • Updating Node Packages (JavaScript)
  • Releasing New Versions
    • When to Release
    • Semantic Versioning
    • Release Process
  • Annual Site Review
    • Content Review
    • Technical Review
    • SEO Review
    • Performance Review
    • Security Review
  • Upgrading Jekyll
    • Before Upgrading
    • Major Version Upgrades
    • Testing After Upgrade
  • Backup and Disaster Recovery
    • What to Back Up
    • Disaster Recovery Checklist
  • Monitoring and Alerts
    • GitHub Notifications
    • Website Monitoring
    • Uptime Monitoring
  • Common Maintenance Tasks
    • Updating Your CV
    • Adding Publications
    • Archiving Old Posts
    • Updating Broken Links
  • Breaking Changes to Watch For
    • Jekyll Major Version Updates
    • Theme Updates
  • Maintenance Schedule
    • Weekly (Automated)
    • Monthly
    • Quarterly (Every 3 months)
    • Annually (Every year)
  • Resources
  • Quick Maintenance Checklist

Overview

Maintenance keeps your site secure, fast, and up-to-date. This guide provides:

• When and how to update dependencies
• Annual review checklist
• How to handle major upgrades
• Disaster recovery procedures

Most maintenance is minimal—usually just dependency updates 2-3 times per year.

---

Dependency Management

Understanding Dependencies

Your site depends on external libraries:

Ruby (Backend):

• Located in Gemfile
• Includes Jekyll, jekyll-scholar, plugins, etc.
• Installed via Bundler

JavaScript (Frontend):

• Located in package.json
• Includes build tools, code formatters, etc.
• Installed via npm

External Libraries (via CDN):

• Bootstrap, MathJax, Font Awesome, etc.
• Versions specified in _config.yml

---

Checking for Updates

Check Ruby gems:

bundle outdated

Shows all outdated gems with current and latest versions.

Check Node packages:

npm outdated

Shows all outdated packages.

Check for security vulnerabilities:

bundle audit     # Check gems for security issues
npm audit        # Check packages for security issues

---

Updating Gems (Ruby)

Safe update (minor versions only):

bundle update --conservative

Updates to latest patch versions (e.g., 4.1.0 → 4.1.5) but not major versions.

Full update (all versions):

bundle update

Updates to latest version including major versions (e.g., 4.x → 5.x).

After updating:

1. Test locally: bundle exec jekyll serve
2. Check for errors in terminal output
3. Visit your site and test all features
4. Deploy: git add Gemfile.lock && git commit -m "Update dependencies"

If something breaks:

• See Breaking Changes section
• Revert with git revert <commit>
• Ask for help in GitHub Discussions

---

Updating Node Packages (JavaScript)

Check for updates:

npm outdated

Update all packages:

npm update

Update a specific package:

npm install package-name@latest

After updating:

1. Test locally: npm run build or docker compose up
2. Check for TypeScript/linting errors
3. Test your site
4. Commit: git add package.json package-lock.json && git commit -m "Update packages"

---

Releasing New Versions

When to Release

A new version of al-folio must be released on GitHub whenever:

• Dependency changes occur – Adding, removing, or upgrading any gems (Ruby) or packages (JavaScript)
• Major features are added – New functionality that benefits users
• Bug fixes are made – Issues affecting functionality or security
• Breaking changes occur – Changes that affect how users configure or use the theme

Dependency updates are significant because they:

• May introduce security patches
• Could include bug fixes or new features
• Might have breaking changes that affect the theme
• Affect Docker image consistency

Semantic Versioning

al-folio follows Semantic Versioning with the format MAJOR.MINOR.PATCH:

MAJOR version (e.g., 1.0.0 → 2.0.0):

• Breaking changes that require users to manually update their configuration
• Major feature overhauls
• Dropping support for older tools or dependencies
• Example: Jekyll 4 → Jekyll 5 migration

MINOR version (e.g., 1.0.0 → 1.1.0):

• New features that don't break existing functionality
• New optional configuration options
• New plugins or integrations
• Example: Adding a new collection type

PATCH version (e.g., 1.0.0 → 1.0.1):

• Bug fixes
• Security patches
• Dependency updates that don't break functionality
• Documentation improvements
• Example: Fixing CSS styling issues or updating gems

Release Process

When releasing a new version:

1. Update version numbers in your repository:

   # Update docker-compose.yml
   # Change: image: amirpourmand/al-folio:vX.X.X
   # Example: v0.16.2 → v0.17.0
   

   Edit docker-compose.yml and update the image tag in the jekyll service:

   services:
     jekyll:
       image: amirpourmand/al-folio:v0.17.0 # Update this version
   

2. Update documentation to reference the new version:

   • INSTALL.md – Update any version references in upgrade instructions
   • QUICKSTART.md – Update if version-specific instructions changed
   • README.md – Update release badges and version references
   • Any other docs mentioning the current version

3. Create a GitHub Release:

   • Go to your repository → Releases → Create a new release

   • Tag version: v0.17.0 (match the format in docker-compose.yml)

   • Release title: Describe the changes (e.g., "Security patch: Update Jekyll" or "New feature: Add xyz")

   • Release notes: List all changes, including:

     • Breaking changes (if any)
     • New features
     • Bug fixes
     • Dependency updates

   • Example format:

     ## What's Changed
     
     ### Breaking Changes
     
     - (none)
     
     ### New Features
     
     - Added support for XYZ
     
     ### Bug Fixes
     
     - Fixed styling issue with mobile nav
     
     ### Dependencies Updated
     
     - Updated Jekyll from 4.2.0 to 4.3.0
     - Updated jekyll-scholar from 5.x to 6.x
     - Updated Bootstrap from 5.1 to 5.2
     

4. Build and publish the Docker image (if applicable):

   • Tag the Docker image with the new version
   • Push to Docker Hub so users can docker compose pull the latest version
   • Ensure the Docker image tag matches the version in docker-compose.yml

5. Communicate the update:

   • Add a GitHub Discussion announcing the release
   • If breaking changes, provide migration guide
   • Link to release notes in important places

User impact:

Users running older versions can upgrade to the new version by:

# Update docker-compose.yml to reference the new version
# Then rebuild and restart
docker compose up --build

Or if using git:

git fetch upstream
git rebase vX.X.X  # Replace with new version tag

---

Annual Site Review

Content Review

Every year, review:

• Is your bio still accurate?
• Are your research interests current?
• Have you added recent publications?
• Are past events still listed (or archived)?
• Do old projects still represent your work?
• Are social media links still active?

Content updates:

# Edit your bio in _pages/about.md
# Update your CV in _data/cv.yml or assets/json/resume.json
# Add new publications to _bibliography/papers.bib

---

Technical Review

Every year, check:

• All external links still work (use browser extensions or CI tools)
• Images load properly
• PDFs are accessible
• No deprecated code or plugins used
• Site works on modern browsers
• Mobile view is responsive

Run automated tests:

# Broken links test (in GitHub Actions)
# Lighthouse performance audit
# Accessibility tests (axe)

---

SEO Review

Every year, review:

• Page titles and descriptions are still accurate
• Alt text is on all images
• No broken links that hurt SEO
• Site speed hasn't degraded
• Search Console shows no errors
• Publications indexed on Google Scholar

Check in Google Search Console:

• Impressions and click-through rate (are you visible?)
• Any crawl errors or coverage issues
• Mobile usability warnings

---

Performance Review

Every year, run:

• Google PageSpeed Insights: https://pagespeed.web.dev/
• Lighthouse audit (built into Chrome)
• Check site load time

Typical targets:

• Load time: < 3 seconds
• Lighthouse score: > 90
• Mobile friendly: Yes

If performance degraded:

• Check image sizes (compress if needed)
• Review page complexity
• Check for unused CSS/JS
• See al-folio performance guide

---

Security Review

Every year:

• Run bundle audit for gem vulnerabilities
• Run npm audit for package vulnerabilities
• Update Gemfile and package.json if issues found
• Check GitHub Security tab for alerts
• Review GitHub Actions permissions

Security checklist:

• No secrets (API keys, tokens) in code
• All dependencies up-to-date
• GitHub token permissions are minimal (read-only by default)
• Site uses HTTPS (GitHub Pages default)

---

Upgrading Jekyll

Before Upgrading

Check current version:

jekyll --version

Read release notes:

• Check Jekyll releases
• Check al-folio releases
• Look for breaking changes

Backup your site (see Disaster Recovery):

git branch backup-current-version

---

Major Version Upgrades

Example: Upgrading Jekyll 4.x → 5.x

1. Update Gemfile:

   bundle update jekyll
   

2. Update other gems:

   bundle update
   

3. Test locally:

   bundle exec jekyll serve
   

4. Look for errors:

   • Check terminal output for warnings
   • Visit http://localhost:4000 and test features

5. If major issues:

   git revert HEAD  # Undo the update
   bundle install  # Restore old version
   

6. If successful:

   git add Gemfile.lock
   git commit -m "Upgrade Jekyll to 5.x"
   

---

Testing After Upgrade

Comprehensive testing:

# 1. Build the site locally
bundle exec jekyll build

# 2. Check for errors
echo "Check for error messages above"

# 3. Start local server
bundle exec jekyll serve

# 4. Test key features:
# - Blog posts display correctly
# - Publications show up
# - Navigation works
# - Styling looks right
# - Search works
# - Comments work (if enabled)

Before deploying:

• Test on mobile
• Test on different browsers (Chrome, Firefox, Safari)
• Test keyboard navigation
• Check all external links

---

Backup and Disaster Recovery

What to Back Up

Your content (most important):

• _posts/ – Blog posts
• _projects/ – Project pages
• _pages/ – Custom pages
• _data/ – CV, social links, publications metadata
• _bibliography/papers.bib – Your publications
• assets/ – Your images, PDFs, documents

Configuration:

• _config.yml – Site settings
• Gemfile, package.json – Dependencies

Everything else is auto-generated (themes, layouts, built site).

Disaster Recovery Checklist

If your repository gets corrupted:

1. Check GitHub: Is the current version safe?

   git status
   

2. Revert to a previous commit:

   git log --oneline | head -20  # See recent commits
   git revert <commit-hash>      # Undo a specific commit
   # OR
   git reset --hard <commit-hash> # Go back to a specific point
   

3. If GitHub is corrupted, restore locally:

   # You have local backups in your git history
   git reflog  # See all actions you've done
   git reset --hard <reference>
   

4. Nuclear option (last resort):

   # Clone a fresh copy of the repo
   git clone https://github.com/yourusername/yourrepo.git new-copy
   
   # Your content in _posts/, _projects/, _data/ is safe
   # Just copy those folders to the new clone
   

To prevent loss:

• GitHub keeps your full history
• Regular pushes = automatic backups
• Consider exporting your content periodically

---

Monitoring and Alerts

GitHub Notifications

Watch your repository for:

• Dependabot alerts (automatic security updates)
• Issues and pull requests
• GitHub Actions failures

Configuration:

• Go to repository Settings → Notifications
• Set how and when you want alerts

Recommended:

• Email for security alerts (critical)
• No email for regular notifications (too noisy)

---

Website Monitoring

Monitor broken links:

• al-folio includes a GitHub Actions workflow for link checking
• Results posted to pull requests
• Fix before merging

Monitor accessibility:

• The axe accessibility workflow runs automatically
• Review results in GitHub Actions tab

---

Uptime Monitoring

Optional: Monitor if your site is down

Tools:

• Cronitor – Simple uptime monitoring
• Uptimerobot – Free tier available
• Statuspage.io – Public status page

Setup (example with Cronitor):

1. Create free account
2. Add your site URL
3. Get notified if it's down
4. Typical response time: 5 minutes

---

Common Maintenance Tasks

Updating Your CV

Option 1: JSON Resume format (recommended):

• Edit assets/json/resume.json
• Update education, experience, skills
• Format follows JSON Resume standard

Option 2: YAML format:

• Edit _data/cv.yml
• If this file exists, it's used instead of JSON
• More human-readable than JSON

After updating:

git add assets/json/resume.json  # or _data/cv.yml
git commit -m "Update CV"
git push

---

Adding Publications

Add to BibTeX:

# Edit _bibliography/papers.bib
# Add a new entry:

@article{newpaper2024,
  title={Your Paper Title},
  author={Your Name and Others},
  journal={Journal Name},
  year={2024},
  volume={1},
  pages={1-10},
  doi={10.1234/doi},
  pdf={newpaper.pdf}  # If you have a PDF
}

If you have a PDF:

1. Save to assets/pdf/newpaper.pdf
2. Add pdf={newpaper.pdf} to BibTeX entry

After updating:

git add _bibliography/papers.bib assets/pdf/
git commit -m "Add new paper"
git push

---

Archiving Old Posts

Move to archive (don't delete):

# Don't delete posts, just move them
# Old posts stay indexed in search engines this way

# Option 1: Add to frontmatter
---
layout: post
title: Old Post (Archived)
date: 2015-01-01
hidden: true
---

# Option 2: Create an archive page
# See _pages/blog.md for archive configuration

---

Updating Broken Links

Find broken links:

• Use Broken Link Checker
• Or use al-folio's broken-link GitHub Actions workflow
• Or browser extension like Checklinks

Fix them:

# Find and replace in files
grep -r "broken-url.com" .

# Update in:
# - Blog posts (_posts/)
# - Pages (_pages/)
# - Data files (_data/)
# - BibTeX entries (_bibliography/)

---

Breaking Changes to Watch For

Jekyll Major Version Updates

Watch for breaking changes in:

• Liquid syntax – How templates work
• Plugin compatibility – Some plugins may not work
• Configuration changes – New or deprecated options
• Folder structure – Where files go

Check al-folio releases before upgrading Jekyll. Major Jekyll updates may require al-folio changes too.

---

Theme Updates

If you customize CSS/layouts:

• Backup your customizations
• Test updates carefully
• Watch for file renames or structure changes

---

Maintenance Schedule

Weekly (Automated)

• ✅ GitHub Actions tests (automated)
• ✅ Lighthouse performance (automated)
• ✅ Accessibility checks (automated)

Monthly

• Check GitHub Dependabot alerts
• Review GitHub Actions log for errors
• Quick visual inspection (is site still working?)

Quarterly (Every 3 months)

• Update dependencies: bundle update --conservative
• Test local build thoroughly
• Check Google Search Console for errors

Annually (Every year)

• Full content review (see Annual Site Review)
• Security audit (bundle audit, npm audit)
• Performance review (Google PageSpeed)
• Technology update assessment
• Consider major version upgrades

---

Resources

• Jekyll Documentation – Official Jekyll docs
• Bundler Guide – Ruby dependency management
• npm Documentation – JavaScript package manager
• GitHub Pages Help – GitHub Pages docs
• al-folio Releases – Track updates
• al-folio Discussions – Ask for help

---

Quick Maintenance Checklist

Monthly:

• Check GitHub notifications
• Review any Dependabot alerts

Quarterly:

bundle outdated     # Check for updates
bundle update --conservative  # Update minor versions
bundle exec jekyll build      # Test locally

Annually:

• Run full annual review (see above)
• Update major dependencies if needed
• Security audit
• Review and update CV/publications
• Update bio if changed

When deploying:

• Test locally first
• Check GitHub Actions log
• Verify site looks correct
• Test on mobile

---

Remember: The best maintenance is regular testing and staying aware of updates. Spend 30 minutes every month checking for updates—it's easier than fixing major issues later!