Changelog System Documentation

Overview

The Changelog system provides a structured way to document changes to the application. It uses Template Toolkit (.tt) files to ensure consistent formatting and proper display of changelog entries in reverse chronological order (newest first).

Back to top

Creating Changelog Entries

To create a new changelog entry:

1. Create a new .tt file in the /Comserv/root/Documentation/changelog/ directory
2. Name the file with the date in YYYY-MM-DD format followed by a brief description, e.g., 2025-10-20-feature-name.tt
3. Use the template format described below

Back to top

Template Format

Each changelog entry should follow this basic structure:

<h1>Your Changelog Title</h1>
<div class="changelog-meta">
    <span class="date">YYYY/MM/DD</span>
    <span class="author">by Your Name</span>
</div>

<div class="changelog-content">
    <h2>Overview</h2>
    <p>Brief description of the changes</p>
    
    <!-- Your changelog content here -->
</div>

<div class="back-link">
    <a href="https://feedthebees.beemaster.ca/Documentation/all_changelog">← Back to All Changelogs</a>
</div>

A complete template file is available at /Comserv/root/Documentation/changelog/changelog_template.tt that you can copy and modify for new entries.

Back to top

Viewing Changelog Entries

Changelog entries can be viewed in two ways:

• Recent Entries: The most recent 5 entries are displayed on the main Documentation page
• All Entries: All changelog entries can be viewed on the All Changelogs page, sorted by date (newest first)

Back to top

Migration from MD Format

The system is transitioning from Markdown (.md) files to Template Toolkit (.tt) files for changelog entries. To convert an existing .md file:

1. Create a new .tt file with the same base name (e.g., convert 2025-10-01-feature.md to 2025-10-01-feature.tt)
2. Use the template format described above
3. Copy the content from the .md file, converting Markdown syntax to HTML
4. Add the metadata section at the top of the file
5. Once verified, the original .md file can be removed

An example of a converted file is available at /Comserv/root/Documentation/changelog/2025-09-starman-restart-fix.tt.

Back to top