Skip to main content
Authoritative format for GitHub release notes on tale-project/tale. The /release slash command drafts notes against this spec, and the in-product “What’s new” link takes users directly to these releases.

​
Why this spec exists

Operators and end-users rely on release notes to know:
  • Whether a security fix affects them.
  • Whether a model or provider change will shift their workflow outputs.
  • Whether an upgrade requires manual steps.
Consistent sectioning — in a consistent order — makes it easy to scan a release for the three things above without reading every bullet.

​
Required sections

Include only the sections that have content. Always use this order:
OrderSection headerScope
1## 🔒 SecurityCVE fixes, dependency patches, auth/session/crypto hardening, secret handling
2## 🤖 Model & ProviderLLM model swap/upgrade/deprecation, provider config changes that alter output
3## 💥 Breaking ChangesAPI removal/renaming, schema changes requiring manual migration, removed features
4## 🚀 FeaturesNew user-visible functionality
5## ⚡ PerformanceMeasurable performance wins worth calling out
6## 🛠 ImprovementsNon-breaking enhancements, UX polish
7## 🐛 FixesBug fixes (non-security)
8## 📝 OtherDocs, refactors, chores — include sparingly

​
Required framing

Every release must include, at minimum:
  1. Title: v{version} — {short tagline}, e.g. v1.6.0 — Usage analytics & multi-tenancy.
  2. Summary: 2–3 sentences at the top describing what changed and why. No emoji.
  3. Upgrade instructions: 
    ## Upgrade

Run `tale upgrade` to update the CLI, then `tale deploy` to apply the new version.
    Both steps are required — tale upgrade fetches the new CLI, tale deploy applies it. Omitting either leaves the deployment on the old version.
  4. Manual migration notes (only when relevant): if any breaking change requires operator action beyond tale deploy, include a ## Migration Guide section with numbered steps.
  5. Full Changelog link at the bottom: 
    **Full Changelog**: https://github.com/tale-project/tale/compare/v{previous}...v{new}

​
Classification rules

  • Security: anything touching authentication, session, secrets storage, crypto, or reachable dependency CVEs. When in doubt, classify as security AND file a Security Advisory.
  • Model & Provider: any change that could alter LLM output for the same user input — model bumps, provider swaps, prompt/template changes in default agents.
  • Breaking Changes: users or operators must do something to keep working after upgrade. If upgrade “just works,” it is not breaking.
  • Other: only for changes worth mentioning that fit nowhere else. Trivial chores (typo fixes, internal refactors, test-only changes) should be omitted.

​
Example

# v1.6.0 — Usage analytics & multi-tenancy

This release adds time-based usage analytics, hardens multi-tenant org isolation,
and bumps the default reasoning model. No breaking changes.

## 🔒 Security

- Tighten org-scoping on governance policy queries (#1573)

## 🤖 Model & Provider

- Default reasoning model bumped from Opus 4.6 → Opus 4.7 (#1590)

## 🚀 Features

- Time-based usage analytics dashboard under `/metrics/usage` (#1574)
- Multi-org support: users can belong to multiple organizations (#1573)

## 🛠 Improvements

- Tabs underline variant adopted across settings surfaces (#1571)

## 🐛 Fixes

- Fix prompt library sidebar scroll on short viewports (#1572)

## Upgrade

Run `tale upgrade` to update the CLI, then `tale deploy` to apply the new version.

**Full Changelog**: https://github.com/tale-project/tale/compare/v1.5.2...v1.6.0
  • The /release slash command in the main repository drafts notes following this spec.
  • Security advisory process — when to also file a GitHub Security Advisory.
Last modified on April 20, 2026