Changelog Diff Files

What is a Changelog Diff?

A changelog diff file (commonly named routes-changelog.diff or similar) is a special file that tracks API route changes between versions. It uses the standard unified diff format to show what endpoints have been added, removed, or modified.

Format Explanation

The diff format follows these conventions:

143a144
> DELETE     /api/admin/activity-categories/events/:category

Understanding the Syntax

• Line numbers: 143a144 means "after line 143, add line 144"
• > prefix: Indicates a line that was added (new route)
• < prefix: Indicates a line that was removed (deleted route)
• HTTP method: The operation type (GET, POST, DELETE, etc.)
• Route path: The API endpoint path with parameters

Real-World Example

Here's a sample from November 4, 2025:

Tue Nov  4 15:57:14 +0545 2025
143a144
> DELETE     /api/admin/activity-categories/events/:category
145a147
> DELETE     /api/admin/activity-categories/volunteerings/:category

This shows: - Date: When the changes were made - Two new DELETE endpoints were added to the API - One for deleting event categories - One for deleting volunteering categories

How to Use Changelog Diffs

1. Tracking API Changes

Keep a running log of all route modifications:

# Append new changes to the diff file
echo "$(date)" >> routes-changelog.diff
echo "143a144" >> routes-changelog.diff
echo "> DELETE     /api/admin/users/:id" >> routes-changelog.diff

2. Reviewing Changes

Read the file to see what's changed over time:

# View all changes
cat routes-changelog.diff

# View recent changes
tail -n 20 routes-changelog.diff

3. Code Review Process

Use diff files during code reviews to: - ✅ Verify all new routes are documented - ✅ Check for breaking changes - ✅ Ensure deprecated routes are properly removed - ✅ Track API versioning

4. Documentation Updates

When you see changes in the diff file, update your: - API documentation - Client SDK - Integration tests - Team communications

Best Practices

✅ Do's

• Commit regularly: Add changes after each API modification
• Include timestamps: Always date your entries
• Be descriptive: Include the full route path with parameters
• Group changes: Keep related changes together
• Version markers: Add version tags for releases

# v2.1.0 - November 4, 2025
143a144
> DELETE     /api/admin/activity-categories/events/:category
145a147  
> DELETE     /api/admin/activity-categories/volunteerings/:category

# v2.0.9 - November 1, 2025
120c121
< GET       /api/events
> GET       /api/v2/events

❌ Don'ts

• Don't manually edit line numbers (they should be generated)
• Don't remove historical entries
• Don't forget to document query parameters or important headers

Generating Changelog Diffs

Automatic Generation

If you have route list files for different versions:

# Compare two route files
diff routes-v1.txt routes-v2.txt > routes-changelog.diff

Manual Entry

For manual tracking:

# Create or append to the file
cat >> routes-changelog.diff << EOF
$(date)
143a144
> DELETE     /api/admin/activity-categories/events/:category
EOF

Integration with Development Workflow

1. Pre-commit Hook

Automatically update the diff when routes change:

#!/bin/bash
# .git/hooks/pre-commit

# Generate current route list
npm run routes:list > routes-current.txt

# Compare with previous version
if [ -f routes-previous.txt ]; then
    diff routes-previous.txt routes-current.txt >> routes-changelog.diff
fi

# Update previous
cp routes-current.txt routes-previous.txt

2. CI/CD Pipeline

Check for undocumented API changes:

- name: Check API Changes
  run: |
    if [ -s routes-changelog.diff ]; then
      echo "API changes detected - ensure documentation is updated"
      cat routes-changelog.diff
    fi

Common Use Cases

Breaking Changes Detection

120d119
< GET       /api/users/:id

This deletion indicates a breaking change - notify all API consumers!

New Features

200a201,203
> POST      /api/v2/notifications
> GET       /api/v2/notifications/:id
> DELETE    /api/v2/notifications/:id

New notification endpoints added - update client documentation.

Route Modifications

150c151
< GET       /api/tasks
> GET       /api/v2/tasks

Versioning change - maintain backward compatibility.

Tools & Automation

Recommended Tools

• diff: Unix diff utility for comparison
• git diff: For version-controlled route files
• API route extractors: Framework-specific tools to list all routes
• Changelog generators: Automated tools for API documentation

Example: Express.js Route Extraction

// scripts/extract-routes.js
const app = require('./app');

function extractRoutes(stack, basePath = '') {
  stack.forEach(layer => {
    if (layer.route) {
      const methods = Object.keys(layer.route.methods)
        .map(m => m.toUpperCase());
      const path = basePath + layer.route.path;
      console.log(`${methods[0]}\t${path}`);
    }
  });
}

extractRoutes(app._router.stack);

Summary

Changelog diff files provide a historical record of API evolution, making it easier to:

• 📝 Track changes over time
• 🔍 Review modifications during code review
• 📢 Communicate updates to stakeholders
• 🔒 Maintain compatibility across versions
• 📚 Keep documentation in sync

Pro Tip

Combine changelog diffs with semantic versioning - increment major version for breaking changes, minor for new endpoints, and patch for modifications.