Updated template to hybrid format combining best of v4.27.0 and v4.25.0:
Benefits from detailed format (v4.25.0):
- 4 complete installation methods (Quick/Docker/Binary/Helm)
- Copy-pasteable commands for each method
- Explicit Downloads section listing what's available
- Better for new users and SEO
Benefits from simple format (v4.27.0):
- Consistent section ordering
- Clean, scannable structure
- Breaking Changes section always present
Changes descriptions now require context and user impact, not just
one-liners. This helps users understand if a change affects them without
clicking through to issues.
Based on Codex analysis that detailed format serves more user types better:
new users, quick upgrades, search indexing, and professional appearance.
Removed hardcoded '31 assets' requirement. Instead, checklist now says:
- Compare with recent successful releases (v4.26.5, v4.27.0)
- Investigate if count differs significantly
- Trust the build script output, not a magic number
This prevents checklist from becoming outdated if build script adds/removes
artifacts. AI can adapt to changes rather than failing on incorrect validation.
Philosophy: Define what good looks like (matches recent releases) rather than
hardcoding specific numbers that will inevitably change.
Changed philosophy from 'follow these exact commands' to 'ensure these
outcomes are true'. This allows AI to be intelligent about HOW to
accomplish goals rather than blindly following steps.
Key changes:
- Focus on WHAT must be true, not HOW to make it true
- Explain WHY each requirement matters
- Document critical constraints (checksums.txt ordering, asset count)
- Provide troubleshooting guidance instead of rigid procedures
- Trust AI to figure out optimal execution path
This approach ensures consistent, reliable releases while allowing
flexibility in execution methods.
User ZaDarkSide reported that checksums.txt was being uploaded last,
causing update failures for users who check immediately after release.
The auto-updater downloads checksums.txt first, but if it's not available
yet, the update fails with 'no checksum file found'.
Changed upload order to:
1. checksums.txt (FIRST - critical for auto-updates)
2. tarballs, zips, helm chart
3. install.sh
4. SHA256 files
This prevents the race condition where fast users get update failures.
