Maintain a Multi-Product Changelog with Git Modules

Executive Summary

This specification defines a unified changelog system that aggregates updates from multiple Parslee products (initially Site, Neo and Parslee) into a single, compelling user experience. The system will support independent content authoring by product teams while providing both product-specific and unified timeline views.

Problem Statement

Current State:

No formal changelog exists for Neo or Parslee
Users lack visibility into product evolution and updates
No centralized place to communicate feature releases, bug fixes, or breaking changes
Product teams have no standardized way to document changes

Target State:

Centralized changelog hub with product-specific and unified views
Consistent format for documenting changes across all products
Visually compelling presentation that encourages engagement
Independent content management by product teams via git submodules
SEO-optimized, searchable, and RSS-enabled for notifications

User Stories & Use Cases

Primary Users

1. End Users / Customers

"As a Neo user, I want to see what's new in the latest release so I can take advantage of new features"
"As a developer using Parslee, I need to know about breaking changes before upgrading"
"As a stakeholder, I want to see all product updates in one place to track organizational progress"

2. Product Teams

"As a Neo product manager, I need an easy way to publish release notes that my team maintains independently"
"As a Parslee developer, I want to document bug fixes without touching other product's content"

3. Support & Marketing

"As a support engineer, I need to quickly reference when a bug was fixed"
"As a marketer, I want to highlight major features in a visually appealing format"

Key Use Cases

Unified Timeline View - See all changes across products in chronological order
Product-Specific View - Filter to only Neo or Parslee updates
Version-Specific View - Deep link to specific release (e.g., /changelog/neo/v1.2.0)
Organizational Momentum and Motivation - Encourage product teams to release often and document changes. Allow the changelog to also document non-release related changes, such as documentation updates, feature enhancements, or internal refactoring. Give developers and product teams the recognition they deserve.
Category Filtering - View only features, fixes, refactors, stack changes, or breaking changes
Search - Find specific changes by keywords/tags.
RSS Subscription - Get notified of new releases per product or unified
Archive Browsing - Navigate historical changes by date or version
SEO Optimization - Ensure changelog pages are discoverable and rank well in search engines. Include meta descriptions, tags, and structured data. Connect to other relevant content, both ways. For instance, articles, how-to-guides, explainers, or case studies.
Email Announcements - Send out email newsletters to customers, product teams and end users, highlighting new features, bug fixes, and breaking changes.
Social Media Integration - Share changelog updates on social platforms like Twitter, LinkedIn, and Facebook to increase visibility and engagement.

Technical Architecture

Content Collections Structure

src/content/
└── changelogs/
    ├── neo/          # Git submodule
    │   ├── v1.0.0.md
    │   ├── v1.1.0.md
    │   ├── 2025-10-15_CSS-Animation-Refactor.md
    │   └── v1.2.0.md
    └── parslee/      # Git submodule
        ├── v0.1.0.md
        ├── v0.2.0.md
        ├── 2025-11-02_AST-Compiler-Enhancements.md
        └── v1.0.0.md

Rationale:

Git submodules allow independent team workflows
Each product team maintains their own repository
Main site pulls updates on build/deploy
Version-based filenames ensure uniqueness and clarity

Collection Configuration (`content.config.ts`)

TYPESCRIPT

  const changelogSchema = z.object({
    version: z.string().optional(),
    title: z.string(),
    lede: z.string().optional(),
    slug: z.string(),
    date_created: z.date().optional(),
    date_modified: z.date().optional(),
    date_started: z.date().optional(),
    date_shipped: z.date().optional(),
    product: z.enum(['Neo', 'Parslee', 'Cilantro-Site']),
    type: z.enum(['Major', 'Minor', 'Patch', 'Documentation', 'Refactor',
  'Infrastructure']),
    is_release: z.boolean().optional().default(false),
    publish: z.boolean().default(true),
    summary: z.string().optional(),
    why_care: z.string().optional(),
    authors: z.array(z.string()).optional(),
    contributors: z.array(z.string()).optional(),
    tags: z.array(z.string()).optional(),
  }); 

const changelogParslee = defineCollection({
  loader: glob({
    pattern: '**/*.md',
    base: './src/content/changelogs/parslee'
  }),
  schema: z.object({
    version: z.string(),
    title: z.string(),
    date: z.date(),
    product: z.literal('parslee'),
    type: z.enum(['major', 'minor', 'patch']),
    published: z.boolean().default(true),
    summary: z.string().optional(),
    author: z.string().optional(),
    tags: z.array(z.string()).optional(),
  }),
});

Markdown Entry Format

Each changelog entry follows this structure:

MARKDOWN

---
version: "1.2.0"
title: "Semantic Code Analysis & Multi-Agent Improvements"
date: 2025-10-01
product: "neo"
type: "minor"
published: true
summary: "Enhanced semantic reasoning with MapCoder integration and improved memory persistence"
author: "Neo Team"
tags: ["semantic-analysis", "performance", "agents"]
---

## 🎉 New Features

### Semantic Code Understanding
- **MapCoder Integration**: Neo now uses multi-agent semantic analysis for deeper code comprehension
- **Persistent Memory**: Cross-session memory retention for better context awareness
- **Enhanced Pattern Recognition**: Improved detection of architectural patterns

## 🐛 Bug Fixes

- Fixed memory leak in long-running agent sessions (#234)
- Resolved issue with nested component analysis (#245)
- Improved error handling for malformed code structures (#256)

## 💥 Breaking Changes

> [!warning] Action Required
> The API endpoint `/analyze` now requires authentication. Update your integration code.

- Authentication now required for all API endpoints
- Deprecated `legacy_mode` flag removed (use `compatibility_mode`)

## 🔧 Improvements

- 40% faster semantic analysis on large codebases
- Reduced memory footprint by 25%
- Better TypeScript inference for complex types

## 📚 Documentation

- New guide: [Getting Started with Semantic Analysis](link)
- Updated API reference for v1.2.0
- Added troubleshooting section for common issues

---

**Migration Guide:** [v1.1.0 to v1.2.0](link)
**Full Changelog:** [View on GitHub](link)

Routing Strategy

URL Structure

/changelog                     # Unified timeline (all products)
/changelog/neo                 # Neo-specific timeline
/changelog/parslee             # Parslee-specific timeline
/changelog/neo/v1.2.0         # Specific version detail
/changelog/parslee/v0.2.0     # Specific version detail
/changelog/rss                # Unified RSS feed
/changelog/neo/rss            # Neo-specific RSS feed
/changelog/parslee/rss        # Parslee-specific RSS feed

Page Implementation

src/pages/
└── changelog/
    ├── index.astro              # Unified view
    ├── [product]/
    │   ├── index.astro          # Product timeline
    │   ├── [version].astro      # Version detail
    │   └── rss.xml.ts           # Product RSS
    └── rss.xml.ts               # Unified RSS

Visual Design Recommendations

Design Principles

Scannable - Users should quickly identify relevant changes
Hierarchical - Clear version → change type → specific changes structure
Branded - Product-specific colors and logos while maintaining cohesion
Responsive - Excellent mobile experience for on-the-go checking
Accessible - WCAG 2.1 AA compliant

Visual Components

1. Unified Timeline View

┌─────────────────────────────────────────────────────┐
│  LOSSLESS CHANGELOG                                 │
│  ───────────────────────────────────────────────    │
│  [All Products ▾] [Features] [Fixes] [Breaking]     │
│                                                      │
│  ┌───────────────────────────────────────────┐      │
│  │ Oct 1, 2025 ● NEO                          │      │
│  │ ───────────────────────────────────────    │      │
│  │ v1.2.0 - Semantic Code Analysis           │      │
│  │                                            │      │
│  │ 🎉 3 New Features                          │      │
│  │ 🐛 8 Bug Fixes                             │      │
│  │ 💥 2 Breaking Changes                      │      │
│  │                                            │      │
│  │ [View Full Release →]                      │      │
│  └───────────────────────────────────────────┘      │
│                                                      │
│  ┌───────────────────────────────────────────┐      │
│  │ Sep 28, 2025 ● PARSLEE                     │      │
│  │ ───────────────────────────────────────    │      │
│  │ v0.2.0 - Marketplace Integration           │      │
│  │ ...                                        │      │
│  └───────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────┘

2. Version Detail View

┌─────────────────────────────────────────────────────┐
│  ← Back to Neo Changelog                            │
│                                                      │
│  [NEO LOGO] NEO v1.2.0                              │
│  Released October 1, 2025 • Minor Release           │
│                                                      │
│  Semantic Code Analysis & Multi-Agent               │
│  Improvements                                        │
│  ──────────────────────────────────────────────     │
│                                                      │
│  Enhanced semantic reasoning with MapCoder          │
│  integration and improved memory persistence.       │
│                                                      │
│  ┌─────────────────────────────────┐                │
│  │ 📥 UPGRADE NOW                  │                │
│  │ npm install @parslee/neo@1.2.0  │                │
│  └─────────────────────────────────┘                │
│                                                      │
│  ▼ TABLE OF CONTENTS                                │
│  • New Features (3)                                 │
│  • Bug Fixes (8)                                    │
│  • Breaking Changes (2)                             │
│  • Improvements (5)                                 │
│  • Documentation                                    │
│                                                      │
│  ════════════════════════════════════════════       │
│                                                      │
│  🎉 NEW FEATURES                                    │
│                                                      │
│  Semantic Code Understanding                        │
│  • MapCoder Integration: Neo now uses...           │
│  • Persistent Memory: Cross-session...             │
│  ...                                                │
└─────────────────────────────────────────────────────┘

Color System

Product Branding:

Neo: Purple/violet theme (#8B5CF6 family)
Parslee: Blue/cyan theme (#06B6D4 family)
Unified: Lossless brand teal (#14B8A6 family)

Change Type Indicators:

🎉 New Features: #10B981 (green)
🐛 Bug Fixes: #F59E0B (amber)
💥 Breaking Changes: #EF4444 (red)
🔧 Improvements: #3B82F6 (blue)
📚 Documentation: #8B5CF6 (purple)
🔒 Security: #DC2626 (dark red)
⚡ Performance: #FBBF24 (yellow)

Component Patterns

Version Badge

HTML

<div class="version-badge minor">
  <span class="label">Minor Release</span>
  <span class="version">v1.2.0</span>
</div>

Major: Bold red border
Minor: Blue border
Patch: Gray border

Product Tag

HTML

<div class="product-tag neo">
  <img src="/logos/neo-icon.svg" alt="Neo" />
  <span>NEO</span>
</div>

Change Type Section

HTML

<section class="change-section new-features">
  <div class="section-header">
    <span class="icon">🎉</span>
    <h2>New Features</h2>
    <span class="count">3</span>
  </div>
  <div class="changes">
    <!-- Individual changes -->
  </div>
</section>

Content Guidelines

Writing Style

DO:

✅ Use clear, action-oriented language ("Added...", "Fixed...", "Improved...")
✅ Lead with user benefit ("You can now...", "Users will see...")
✅ Include issue/PR numbers for traceability
✅ Link to relevant documentation
✅ Use emojis for visual scanning
✅ Highlight breaking changes prominently

DON'T:

❌ Use jargon without explanation
❌ Write in passive voice ("Bug was fixed...")
❌ Omit context for technical changes
❌ Forget migration guides for breaking changes
❌ Include internal ticket numbers without context

Change Categories

🎉 New Features

Brand new capabilities
New API endpoints
New configuration options

🐛 Bug Fixes

Resolved issues
Error corrections
Behavior fixes

💥 Breaking Changes

API changes requiring code updates
Removed features
Changed default behavior

🔧 Improvements

Performance enhancements
UX refinements
Refactoring (user-visible impact)

📚 Documentation

New guides
Updated references
Tutorial additions

🔒 Security

Security patches
Vulnerability fixes
Authentication changes

⚡ Performance

Speed improvements
Resource optimization
Scalability enhancements

🗑️ Deprecations

Features marked for removal
Warnings about future changes

Version Numbering

Follow Semantic Versioning 2.0.0:

Major (X.0.0): Breaking changes, major features
Minor (0.X.0): New features, backward compatible
Patch (0.0.X): Bug fixes, small improvements

Prerelease Tags:

v1.2.0-alpha.1 - Early testing
v1.2.0-beta.2 - Feature complete, testing
v1.2.0-rc.1 - Release candidate

Interactive Features

1. Filtering & Search

Filters:

Product (Neo, Parslee, All)
Change Type (Features, Fixes, Breaking, etc.)
Version Type (Major, Minor, Patch)
Date Range (Last 30 days, Last 6 months, All time)

Search:

Full-text search across all changelog entries
Highlight matching terms
Search within specific product or across all

2. Table of Contents

Auto-generated TOC for each version detail page:

Jump to specific change type sections
Show counts per section
Sticky navigation on scroll

3. Notification Options

┌─────────────────────────────────┐
│ 🔔 STAY UPDATED                 │
│                                 │
│ Subscribe to changelog updates: │
│                                 │
│ ☐ Neo releases                  │
│ ☐ Parslee releases              │
│ ☐ All products                  │
│                                 │
│ Via: [RSS] [Email] [Webhook]    │
└─────────────────────────────────┘

Share specific versions on Twitter/LinkedIn
Copy direct link to version
Embed widget for external sites

Technical Implementation Details

Aggregation Logic

TYPESCRIPT

// Pseudo-code for unified timeline
async function getUnifiedChangelog() {
  const neoEntries = await getCollection('changelog-neo',
    ({ data }) => data.published === true
  );
  const parsleeEntries = await getCollection('changelog-parslee',
    ({ data }) => data.published === true
  );

  const allEntries = [...neoEntries, ...parsleeEntries]
    .sort((a, b) => b.data.date.getTime() - a.data.date.getTime());

  return allEntries;
}

RSS Feed Generation

TYPESCRIPT

// src/pages/changelog/rss.xml.ts
export async function GET(context) {
  const entries = await getUnifiedChangelog();

  return rss({
    title: 'Lossless Product Updates',
    description: 'Latest changes across all Lossless products',
    site: context.site,
    items: entries.map(entry => ({
      title: `${entry.data.product.toUpperCase()} ${entry.data.version}: ${entry.data.title}`,
      pubDate: entry.data.date,
      link: `/changelog/${entry.data.product}/${entry.data.version}`,
      description: entry.data.summary,
    })),
  });
}

Git Submodule Setup

BASH

# Initial setup
git submodule add <neo-changelog-repo-url> src/content/changelogs/neo
git submodule add <parslee-changelog-repo-url> src/content/changelogs/parslee

# .gitmodules entry
[submodule "src/content/changelogs/neo"]
  path = src/content/changelogs/neo
  url = <neo-changelog-repo-url>
  branch = main

[submodule "src/content/changelogs/parslee"]
  path = src/content/changelogs/parslee
  url = <parslee-changelog-repo-url>
  branch = main

Build Process

JAVASCRIPT

// Update submodules before build
"scripts": {
  "prebuild": "git submodule update --remote --merge",
  "build": "astro build"
}

SEO & Discoverability

Meta Tags

Each version page includes:

HTML

<meta name="description" content="{version.data.summary}" />
<meta property="og:title" content="{product} {version} - {title}" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="{version.data.date}" />
<meta name="twitter:card" content="summary_large_image" />

Structured Data

JSON

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Neo v1.2.0 - Semantic Code Analysis",
  "datePublished": "2025-10-01",
  "author": {
    "@type": "Organization",
    "name": "Lossless Group"
  },
  "about": "Software Release Notes"
}

Sitemap

Include all published changelog entries:

XML

<url>
  <loc>https://site.com/changelog/neo/v1.2.0</loc>
  <lastmod>2025-10-01</lastmod>
  <changefreq>monthly</changefreq>
  <priority>0.8</priority>
</url>

Analytics & Metrics

Key Metrics to Track

Engagement
- Pageviews per changelog entry
- Time on page
- Scroll depth
- Click-through rate to documentation
Content Performance
- Most viewed versions
- Most shared releases
- Search queries
- Filter usage patterns
User Behavior
- Product-specific vs unified view ratio
- RSS subscription rate
- Return visitor rate
- External referrals

Implementation

JAVASCRIPT

// Track changelog view
analytics.track('Changelog Viewed', {
  product: 'neo',
  version: 'v1.2.0',
  changeType: 'minor',
  source: 'direct' | 'unified' | 'rss'
});

Accessibility Requirements

WCAG 2.1 AA Compliance

✅ Keyboard navigation for all interactive elements
✅ ARIA labels for icon-only buttons
✅ Sufficient color contrast (4.5:1 minimum)
✅ Focus indicators on all focusable elements
✅ Screen reader announcements for filter changes
✅ Alt text for product logos
✅ Semantic HTML structure (proper heading hierarchy)

Skip Links

HTML

<a href="#main-content" class="skip-link">
  Skip to changelog content
</a>

Reduced Motion

CSS

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Future Enhancements

Phase 2 Considerations

Version Comparison
- Side-by-side diff view between versions
- "What's changed since v1.0.0" tool
Release Calendar
- Visual calendar showing release cadence
- Upcoming releases (roadmap integration)
Impact Badges
- "High Impact" for major features
- "Action Required" for breaking changes
- "Recommended Update" for security patches
Integration Widgets
- Embeddable changelog widgets for other sites
- Discord/Slack webhooks for new releases
- GitHub integration for automated entries
Localization
- Multi-language changelog support
- Automatic translation for major releases
User Feedback
- "Was this helpful?" voting
- Comment section for release discussions
- Bug report links

Success Criteria

Launch Metrics (30 days post-launch)

✅ 70%+ of active users visit changelog at least once
✅ Average time on page > 2 minutes (indicates reading)
✅ RSS subscription rate > 5% of weekly active users
✅ < 5% bounce rate on unified changelog page
✅ Zero critical accessibility violations

Content Quality

✅ All releases documented within 24 hours of deployment
✅ 100% of breaking changes include migration guides
✅ 90%+ of entries link to relevant documentation
✅ User feedback scores > 4/5 for helpfulness

Technical Performance

✅ Page load time < 2 seconds (LCP)
✅ Perfect Lighthouse accessibility score
✅ SEO score > 95
✅ Zero console errors

Open Questions & Decisions Needed

Email Notifications
- Do we want to build email subscription system?
- If yes, which email service provider?
- Frequency: immediate, daily digest, weekly?
Authentication
- Are changelogs public or require login?
- If public, any content restrictions?
Pre-release Versions
- Should alpha/beta releases appear in public changelog?
- Separate "Early Access" section?
Historical Content
- How far back should we backfill changelogs?
- Who owns historical data entry?
Automated vs Manual
- Can we auto-generate entries from git commits?
- Or purely manual curation?
Versioning for Multiple Packages
- If Neo has sub-packages (e.g., neo-core, neo-cli), how do we handle versioning?
- Monorepo version strategy?

Appendix

A. Example Changelog Entry (Full)

See "Markdown Entry Format" section above for complete example.

B. Component Library Dependencies

Recommended Svelte Components:

ChangelogTimeline.svelte - Unified timeline view
VersionCard.svelte - Summary card for each version
ChangelogFilters.svelte - Filter interface
ProductBadge.svelte - Product identifier
ChangeTypeSection.svelte - Collapsible change sections
TableOfContents.svelte - Sticky TOC navigation
SearchBar.svelte - Full-text search interface

C. Git Submodule Workflow

Product Team Workflow:

BASH

# In Neo changelog repo
echo "---
version: "1.2.0"
title: "New Feature"
date: 2025-10-01
product: "neo"
type: "minor"
---

## New Features
- Added semantic analysis
" > v1.2.0.md

git add v1.2.0.md
git commit -m "Release v1.2.0"
git push

Site Update Workflow:

BASH

# In main site repo
git submodule update --remote --merge
git add src/content/changelogs/neo
git commit -m "Update Neo changelog"
git push

# Triggers rebuild and deploy

D. URL Redirects

Legacy URL Support (if applicable):

/releases/neo/1.2.0 → /changelog/neo/v1.2.0
/news/parslee → /changelog/parslee

Implementation Checklist

Phase 1: MVP (Weeks 1-2)

Create git submodule repositories for Neo and Parslee
Configure content collections in content.config.ts
Build basic routing structure (/changelog/*)
Create ChangelogLayout.astro base layout
Implement unified timeline view
Build product-specific timeline views
Create version detail page template
Add basic filtering (product, change type)
Implement RSS feeds (unified + per-product)
Style with Tailwind following design system
Add mobile responsive design
Implement dark mode support
Write content guidelines documentation
Create example changelog entries for each product
Test git submodule workflow

Phase 2: Enhancement (Weeks 3-4)

Add full-text search functionality
Build interactive filters with state management
Implement table of contents for detail pages
Add social sharing capabilities
Create embeddable changelog widgets
Set up analytics tracking
Implement structured data for SEO
Add accessibility audit and fixes
Create product team documentation
Build version comparison tool

Phase 3: Polish (Week 5)

Performance optimization
Cross-browser testing
Accessibility compliance verification
Content migration (if historical data exists)
User acceptance testing
Documentation review and finalization
Launch communications preparation

Sign-off

Requires approval from:

Product Management
Engineering Lead
Design Lead
Neo Product Owner
Parslee Product Owner
Marketing/Communications

Questions or feedback? Contact product team or open a discussion in the project repository.

I have a question: our other sites use a unified content.config.ts and to be honest it's gotten out of hand. I have sometimes noticed that my AI Assistant will put a config.ts file in the folder with the actual content. However, it can get confusing when using search because multiple config.ts files will show up. Is there a way to call it something like changelogParslee.config.ts and put it in the folder with the content? or maybe changelog.config.ts and all changelogs are in subfolders but the content config is in the unified changelog folder?

⏺ Excellent question! Yes, Astro absolutely supports this pattern, and it's actually recommended for large projects with multiple content collections. You can create modular config files and import them into the main content.config.ts.

Recommended Approach

Put a changelog.config.ts in the src/content/changelogs/ folder, and import it in your main config:

TEXT

src/content/
├── config.ts                    # Main aggregator (imports everything)
└── changelogs/
    ├── changelog.config.ts      # Changelog-specific config
    ├── neo/                     # Git submodule
    └── parslee/                 # Git submodule

Implementation

src/content/changelogs/changelog.config.ts:

import { z, defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const changelogSchema = z.object({
  version: z.string().optional(),
  title: z.string(),
  date: z.date(),
  product: z.enum(['neo', 'parslee', 'site']),
  type: z.enum(['major', 'minor', 'patch', 'documentation', 'refactor',
'infrastructure']),
  published: z.boolean().default(true),
  summary: z.string().optional(),
  author: z.string().optional(),
  tags: z.array(z.string()).optional(),
});

export const changelogNeo = defineCollection({
  loader: glob({
    pattern: '**/*.md',
    base: './src/content/changelogs/neo'
  }),
  schema: changelogSchema.extend({
    product: z.literal('neo'),
  }),
});

export const changelogParslee = defineCollection({
  loader: glob({
    pattern: '**/*.md',
    base: './src/content/changelogs/parslee'
  }),
  schema: changelogSchema.extend({
    product: z.literal('parslee'),
  }),
});

export const changelogSite = defineCollection({
  loader: glob({
    pattern: '**/*.md',
    base: './src/content/changelogs/site'
  }),
  schema: changelogSchema.extend({
    product: z.literal('site'),
  }),
});

src/content/config.ts (becomes a simple aggregator):

import { defineCollection } from 'astro:content';

// Import existing collections
import { essays, concepts, vocabulary } from './knowledge-base.config';
import { tooling, verticalToolkits } from './tooling.config';
import { changelogNeo, changelogParslee, changelogSite } from
'./changelogs/changelog.config';

export const collections = {
  // Knowledge base
  essays,
  concepts,
  vocabulary,

  // Tooling
  tooling,
  'vertical-toolkits': verticalToolkits,

  // Changelogs                                                                                'changelog-neo': changelogNeo,
  'changelog-parslee': changelogParslee,                                                       'changelog-site': changelogSite,
};

Benefits

Modular Organization - Each domain owns its own config 2. Better Search - changelog.config.ts is more descriptive than generic config.ts
Team Ownership - Product teams can own their changelog config 4. Easier Maintenance - Changes don't require editing a massive central file
Git Submodule Friendly - Config can even live IN the submodule if you want Alternative: Config in Submodule

If you want each product team to fully own their config, you could even put it IN the submodule:

TEXT

src/content/changelogs/
├── neo/                              # Git submodule
│   ├── neo-changelog.config.ts      # Product team owns this
│   ├── v1.0.0.md
│   └── v1.1.0.md
└── parslee/                          # Git submodule
    ├── parslee-changelog.config.ts
    ├── v0.1.0.md
    └── v0.2.0.md

Then import from submodules in your main config: // src/content/config.ts

import { changelogNeo } from './changelogs/neo/neo-changelog.config';
import { changelogParslee } from './changelogs/parslee/parslee-changelog.config';

My Recommendation

Option 1 (shared changelog.config.ts in parent folder) is probably best because:

Schema consistency across products
Easier to enforce standards
Less duplication
Product teams still maintain content independently

But Option 2 (config in each submodule) gives maximum autonomy if teams want different schemas or have different needs.

Neo's Architectural Analysis Complete

I've completed a comprehensive evaluation of your multi-product changelog architecture. Here are the key findings:

Overall Assessment: 8.3/10 - Strong foundation with clear optimization opportunities

Critical Issues to Address

Parslee Submodule Problem (High Priority)

Your git submodule shows uncommitted changes: -39ec2accd4386ee83f8c299553f7eaf5008f7a02 src/content/changelogs/changelog-parslee

The minus sign indicates a detached HEAD or uncommitted state. This needs immediate attention.

Date Field Confusion (High Priority)

You have 4 date fields (date_created, date_modified, date_started, date_shipped) but your routing code only uses date_shipped. This creates issues for non-release entries that may not have a ship date.

Recommendation: Establish a clear date hierarchy with fallbacks in your sorting logic.

Scalability Concerns (Medium Priority)

No pagination implemented yet (becomes critical around 100+ entries)
Fetching all collections on every page load
No query-level filtering

What's Working Well

✅ Modular config approach - Your changelog.config.ts separation is exactly right✅ Clean routing structure - SEO-friendly URLs with good hierarchy✅ Product-specific type literals - Prevents misconfiguration✅ Rich metadata schema - Good balance of required vs optional fields

Key Recommendations

Fix the submodule issue - See detailed commands in Neo's analysis
Simplify date strategy - Use primary date field with fallbacks
Add pagination proactively - Before you hit 50+ entries
Create authoring tools - CLI generator for new changelog entries
Add validation hooks - Catch schema errors before build time

Architecture Decision Validation

Your git submodules approach is appropriate for your context since:

You're in a monorepo with multiple products
Teams may want independent content ownership
The modular config file approach you chose is ideal

Next Steps

Would you like me to:

Fix the Parslee submodule issue (5 mins)
Create a changelog entry generator script (15 mins)
Update schema with simplified date handling (10 mins)
Add pagination to unified view (20 mins)

The full analysis from Neo includes detailed code examples, risk scores, and implementation roadmap. Which priority would you like to tackle first?

Executive Summary

Problem Statement

User Stories & Use Cases

Primary Users

Key Use Cases

Technical Architecture

Content Collections Structure

Collection Configuration (content.config.ts)

Markdown Entry Format

Routing Strategy

URL Structure

Page Implementation

Visual Design Recommendations

Design Principles

Visual Components

1. Unified Timeline View

2. Version Detail View

Color System

Component Patterns

Version Badge

Product Tag

Change Type Section

Content Guidelines

Writing Style

Change Categories

Version Numbering

Interactive Features

1. Filtering & Search

2. Table of Contents

3. Notification Options

4. Social Sharing

Technical Implementation Details

Aggregation Logic

RSS Feed Generation

Git Submodule Setup

Build Process

SEO & Discoverability

Meta Tags

Structured Data

Sitemap

Analytics & Metrics

Key Metrics to Track

Implementation

Accessibility Requirements

WCAG 2.1 AA Compliance

Skip Links

Reduced Motion

Future Enhancements

Phase 2 Considerations

Success Criteria

Launch Metrics (30 days post-launch)

Content Quality

Technical Performance

Open Questions & Decisions Needed

Appendix

A. Example Changelog Entry (Full)

B. Component Library Dependencies

C. Git Submodule Workflow

D. URL Redirects

Implementation Checklist

Phase 1: MVP (Weeks 1-2)

Phase 2: Enhancement (Weeks 3-4)

Phase 3: Polish (Week 5)

Sign-off

Collection Configuration (`content.config.ts`)