The original changelog format had both developer and public summaries in a single file, making it awkward to share release notes with users without exposing technical implementation details.
Split changelog output into two separate files: changelog.md for developer notes and changelog-public.md for user-facing release notes.
-
Single file with both sections
- Pros: Everything in one place, simpler
- Cons: Can't share public notes without showing technical details
-
Two separate files
- Pros: Clean separation, can share public notes directly
- Cons: Two files to maintain
Two separate files in the same location
User-facing release notes should be shareable without exposing internal implementation details. The public file can be directly used in app stores, release announcements, etc.
Two files instead of one, but cleaner separation of concerns
- None
Initially assumed WhatToTest.txt must be in a TestFlight/ folder per Apple requirements, but discovered some projects keep it at project root.
Make WhatToTest location configurable with TestFlight folder as the recommended default.
-
Hardcoded to TestFlight folder
- Pros: Follows Apple convention
- Cons: Doesn't work for all project structures
-
Configurable with default
- Pros: Flexible, works for any project
- Cons: Extra prompt on first run
Configurable with TestFlight folder as recommended default
Real-world usage showed the file location varies by project. Better to be flexible than prescriptive.
Extra configuration option, but accommodates more workflows
- User feedback from testing in other projects
WhatToTest prompt was appearing for all projects, even non-iOS projects where TestFlight isn't relevant.
Auto-detect Xcode projects before showing WhatToTest prompt.
-
Always prompt
- Pros: Simple, user can decline
- Cons: Annoying for non-iOS projects
-
Auto-detect with override
- Pros: Smart defaults, still configurable
- Cons: Detection might miss edge cases
Auto-detect by checking for .xcodeproj, .xcworkspace, Package.swift, or Podfile. Allow override via config.
Most users won't want TestFlight prompts in non-iOS projects. Detection covers common cases, config handles edge cases.
Might miss unusual Xcode project structures, but config override available
- None
When creating the changelog plugin, we needed to decide whether to structure it as a single plugin or as a marketplace containing multiple plugins.
Structure as a single plugin within a marketplace wrapper.
-
Single plugin repo
- Pros: Simpler structure, easier to maintain
- Cons: Can't add more plugins to same repo later
-
Marketplace with multiple plugins
- Pros: Can distribute multiple plugins from one repo
- Cons: More complex structure, overkill for one plugin
Single plugin - the repo is both a marketplace (has marketplace.json) and contains one plugin. Can expand later if needed.
Simpler to start with, and the marketplace.json wrapper allows future expansion without restructuring.
Commands are namespaced (e.g., /release:changelog instead of /changelog)
The plugin needs to store user preferences in .claude/config.json, but this file is shared across all plugins.
Namespace all config under changelog-plugin key to avoid conflicts with other plugins.
-
Flat keys (
"changelog": {...})- Pros: Simpler, shorter paths
- Cons: Risk of collision with other plugins
-
Namespaced keys (
"changelog-plugin": {"changelog": {...}})- Pros: No collision risk, clear ownership
- Cons: Longer paths, slightly more complex
Namespace under changelog-plugin
Safety over convenience - config conflicts would be confusing and hard to debug.
More verbose config paths
- None
Needed a changelog format that serves both developers (detailed technical info) and end users (simple release notes).
Problem/Solution format with two summaries: Internal Developer Summary and Public User-Facing Summary.
-
Standard Keep a Changelog format
- Pros: Industry standard, familiar
- Cons: Lacks technical depth, single audience
-
Problem/Solution with dual summaries
- Pros: Comprehensive developer notes, clean user notes, captures "why"
- Cons: More verbose, more work to generate
Problem/Solution with dual summaries
Developer notes capture institutional knowledge (why decisions were made, how things work). User-facing summary derived from developer notes ensures consistency.
Longer changelog files, but both audiences served well
- User's existing documentation standards
WhatToTest.txt could either be overwritten each release or accumulate history.
Give user choice: prepend (keep history) or replace (fresh start).
-
Always overwrite
- Pros: Clean, only shows current release
- Cons: Loses historical context
-
Always prepend
- Pros: Full history preserved
- Cons: File grows, may not be desired
-
Ask user each time
- Pros: Flexibility
- Cons: Extra prompt
Ask user, with option to save preference to config
Different teams have different needs - some want clean files, some want history. Let them choose and persist the choice.
Extra prompt on first run
Different projects organize documentation differently - root, docs/, custom folders.
Prompt for location if file doesn't exist, with option to persist choice.
-
Fixed location (root)
- Pros: Simple, predictable
- Cons: Doesn't fit all projects
-
Configurable with prompt
- Pros: Flexible, remembers choice
- Cons: Extra prompt on first run
Configurable with prompt and persistence option
One-time prompt is worth the flexibility. Most users will set it once and forget.
Slightly more complex first-run experience
- None
Originally planned as analysis.md for research and deep-dives, but questioned whether Claude already tracks this.
Rename to decisions.md focused on decisions and proposals (implemented or not).
-
analysis.md - Research, comparisons, deep-dives
- Pros: Comprehensive technical documentation
- Cons: Overlaps with what Claude tracks in session
-
decisions.md - Decisions and proposals only
- Pros: Focused, captures what Claude doesn't persist (rationale)
- Cons: Narrower scope
decisions.md with status tracking (Implemented, Proposed, Deferred, Rejected)
Claude doesn't persist between sessions. Decisions and their rationale are the most valuable things to capture - they answer "why" months later.
Less comprehensive than full analysis docs, but more focused and useful
- None