chat-release-notes

# DIAL Chat release-notes enhancer The CI publishes a release for every tag with bullets that are just the PR titles. Those bullets carry a lot of dirt — conventional-commit prefixes (`feat(chat):`, `fix(chat):`, `feat(chat-e2e):`, `fix(overlay):`), branch-style phrasing inherited from the PR title, duplicate entries when the same issue was patched twice (e.g. two `(Issue #4696) (#6135)` / `(#6430)` bullets in `0.45.0`), `Revert "..."` lines that were never reconciled with their original entry, and a `## Other` section that mixes maintainer-relevant bumps with pure tooling churn. The releases visible at `https://github.com/epam/ai-dial-chat/releases` from `0.43.x` through `0.45.1` are what those raw notes look like after a human editorial pass. This skill reproduces that pass. You are running in a forked, isolated context. Read and research freely — only the final summary you return reaches the main conversation. All file writes happen in this fork; the draft lands at `claude/release-notes/<tag>-draft.md`. ## When to use - "Enhance the release notes for `0.45.0-rc.55`" - "Look at the latest pre-release notes and refine them" - "Help me adjust release notes for the current rc" - "The CI just published `<tag>`, make it readable" Do **not** trigger on requests like "what changed in 0.45.0?" — that is a recall question, not a notes-editing task. ## Inputs `tag` = `$tag` — the GitHub release tag to enhance (e.g. `0.45.0-rc.55`, `0.46.0`). If empty, pick the most recent tag from `gh release list --limit 5` and confirm with the user before editing. ## Workflow ### 1. Resolve target and reference styles 1. `gh release view <tag> --json body,name,tagName` — capture the raw CI notes. 2. `gh release list --limit 10` — locate the previous tag of the same kind (last stable for a stable release, the predecessor `rc` for a delta `rc.N+1`). 3. `gh release view <prev-stable-tag> --json body` and `gh release view <prev-rc-tag> --json body` (when relevant) — these are the style anchors. The user has repeatedly insisted **"keep the same format as the latest stable release"** and **"your notes are too verbose"** — match the terseness of those notes, not your own instincts. One line per bullet. 4. `git tag --list | sort -V` + `git log <prev-tag>..<tag> --oneline` — full commit list for the range, so you can spot hotfix commits the CI dropped because they had no PR. ### 2. Pull source context for each bullet For every bullet in the raw notes: 1. Parse out the trailing `#<issue> (#<PR>)` or `(#<PR>)`. If only a PR number is present, that's the canonical reference; if both, keep `#<issue> (#<PR>)` order. 2. `gh pr view <PR> --json title,body,labels` — read the PR body, not just the title. The body is where the _why_ and the _what-it-replaces_ live; the title is usually too compressed. 3. For bullets without a PR number, find the commit with `git log <prev-tag>..<tag> --oneline | grep -i <keywords>` and `git show <hash>` — usually a hotfix commit that should fold into a related entry. 4. If a PR body references a doc under `docs/`, `apps/chat-api/README.md`, or `libs/chat-overlay/README.md`, skim it for the headline framing. Use the `dial-docs` skill to resolve which doc under `docs/` is authoritative rather than guessing a filename. ### 3. Cross-check `config-registry.constants.ts` / source for deployment changes The frontend (`apps/chat`) does not read env vars directly — all runtime config and feature flags are resolved server-side by `apps/chat-api` and served to the client through `AppConfigContext`. The `Deployment Changes` section is built from primary sources, not PR titles: - `git diff <prev-tag>..<tag> -- apps/chat-api/src/app-config/config-registry/config-registry.constants.ts` — this `CONFIG_DEFINITIONS` array is the canonical registry for **both** operator-facing config values and feature flags. Each entry has `key`, `type` (`'config'` or `'feature'`), `valueType`, `visibility`, `defaultValue`, `description`, `owner`, and optionally `envVar` / `allowedRolesEnvVar`. Additions/removals/changed `defaultValue` here are deployment-relevant. - `git diff <prev-tag>..<tag> -- apps/chat-api/src/config/environment.config.ts` — the `EnvironmentVariables` class validated at boot; this is the source of truth for raw env var names, whether they're required, and their type/validation. Code wins over docs when a name conflicts. - `git diff <prev-tag>..<tag> -- apps/chat-api/README.md` — curated, human-readable env var tables (grouped by concern: auth, DIAL Core, themes, file transfer/archives, deployments/catalog, voice/ASR, utility model). Use these for the description/default columns, but verify the **canonical name** against `environment.config.ts` or the `envVar` field in `config-registry.constants.ts` — past releases have caught doc typos this way. - Confirm defaults by reading the `defaultValue` field in `config-registry.constants.ts`, or the access-site fallback in `environment.config.ts` when the var isn't in the registry. - Entries in `CONFIG_DEFINITIONS` with `type: 'feature'` are the feature flags (see `apps/chat-api/src/app-config/feature-flags/feature-key.enum.ts` for the `FeatureKey` enum backing them). A removed entry means the flag no longer has any effect. The registry's `description` field is the source of truth for what the flag does — same "code wins" rule as env vars. Flags are resolved dynamically (env var + optional `allowedRolesEnvVar` role restriction) via `FeatureFlagsService`, not through a single `ENABLED_FEATURES` blob — do not describe them as such. ### 4. Classify each bullet (move things between sections, drop the noise) The raw notes' `## Features` / `## Fixes` / `## Other` partition is unreliable because CI keys it off the conventional-commit prefix in the PR title. Reclassify by the change's actual user impact: | Where CI put it | Where it belongs | Rule | | ------------------------------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------- | | `Other` starting with `feat(...)` | `Features` | A feat that lost its slot to a scope prefix. | | `Other` starting with `fix(...)` | `Fixes` | Same, for fix. | | `Features` / `Fixes` for a pre-release-only regression | `Fixes` with note "(affects pre-release users of \<feature\> only)" | Don't surface a transient bug as a feature. | | `Other` for a security CVE bump | `Fixes` | Security items are user-relevant. | | Multiple PRs / hotfix commits on one feature | one folded entry under the appropriate section | Cite the commit hashes or PR numbers in parens. | **Drop these from the notes entirely** — they have no consumer-visible effect: - All `feat(chat-e2e):` / `fix(chat-e2e):` / `chore(chat-e2e):` items unless the PR also touches `apps/chat/src` in a behavior-changing way (verify via `gh pr view --json files`). - Pure refactors / formatting / lint / tsconfig / `nx.json` / `project.json` / Nx project-graph shuffles (`chore(chat): refactor utils`, `chore: bump nx`). - CI / workflow changes (`.github/workflows/**`) **unless** a maintainer needs to know — then keep under `Other` with a one-line rationale. - Pure dependency bumps with no CVE / no behavior delta (`chore: bump types/node`). - `Merge remote-tracking branch …` commits. - Claude Code agent setup / docs / skill scaffolding. **Keep in `Other`** — items maintainers, embedders, or themers care about even if they're not features: - Security-adjacent dependency bumps (`bump axios`, `bump next`). - `dial-ui-kit` (visible default styles). - Forwarded-headers / auth-handling checks. - Issue templates, contributor docs (visible to contributors). If you find yourself unsure whether to drop a bullet, ask: _would a customer reading these notes care that this happened?_ If no, drop it. ### 5. Rewrite each kept bullet The raw form is `* <conventional-prefix(scope)>: <PR title> (Issue #<N>) (#<PR>)`. Rewrite to: ``` * <Active-voice description of what changed> — <brief why-it-matters or what-it-replaces> (Issue #<N>) (#<PR>) ``` Rules in order of importance: 1. **One line per bullet.** No multi-paragraph descriptions. The user has explicitly flagged "too verbose" in prior runs. If you need more detail, save it to the companion editorial-notes file (see §8), not the main draft. 2. **Drop the conventional prefix** (`feat(chat):`, `fix(chat):`, `feat(overlay):`, `fix(i18n):`). Replace with prose. 3. **Drop branch-style phrasing.** `add prop to hide item name in path` → `Hide the item name segment in breadcrumb paths via a new prop`. The PR title is the prompt, not the output. 4. **Use a `—` em-dash for the "why" clause**, not a hyphen or colon — that's the consistent house style across `0.43.x`–`0.45.x`. 5. **Backticks for code identifiers**: env vars (`THEMES_CONFIG_HOST`, `LIVE_CHAT_INTERACTION_ENABLED`), feature-flag keys (`features.asrEnabled`), file paths, prop names, type names, overlay-API method names. 6. **Preserve issue + PR refs at the end** in `(Issue #<N>) (#<PR>)` parenthesised form, or `(#<PR>)` when there is no issue. Don't strip them — these notes ship as the GitHub release body where the numbers auto-link. 7. **Prefix with `[Preview]`** for preview-gated features. 8. **Flag regressions explicitly**: `(regression fix)` for items restoring previously-working behavior. 9. **Quote CVE IDs verbatim** for security upgrades: `Upgrade axios to 1.7.9 to address CVE-2024-39338`. #### Example transformations Each pair is `raw CI` → `enhanced`. Backticks in the enhanced form denote code identifiers in the actual output. ``` # Dropping `feat(chat):`, naming the concrete prop and surface: - * feat(chat): add prop to hide item name in path (Issue #6210) (#6292) + * Hide the item name segment in breadcrumb paths via a new `hideItemNameInPath` prop on path-rendering components (Issue #6210) (#6292) # Removing `fix(chat):` and naming the precise gap, marking regression: - * fix(chat): fix quick app review flow when orchestrator does not support temperature (Issue #6637) (#6688) + * Fix Quick App review flow when the orchestrator deployment does not advertise `temperature` support (regression fix) (Issue #6637) (#6688) # Folding two PRs that patched the same issue into one bullet: - * fix(chat): publication request scrolling (Issue #4696) (#6135) - * fix(chat): publication request scrolling follow-up (Issue #4696) (#6430) + * Fix scrolling inside the publication-request panel when the list overflows the viewport (Issue #4696) (#6135, #6430) # Reverts whose original is in the same range — drop both: - * feat(chat): introduce experimental thread-grouping (#6401) - * Revert "feat(chat): introduce experimental thread-grouping" (#6488) + (drop both — net zero in the range) # Revert whose original shipped earlier — keep, rephrase as roll-back: - * Revert "feat(chat): aggressive prefetch of conversation history" (#6404) + * Roll back the aggressive prefetch of conversation history shipped in `0.44.0` — restores prior load-on-demand behavior (#6404) # Dropping `feat(chat-e2e):` entirely (test-only): - * feat(chat-e2e): updated tests with expand/collapse attachment feature (#6541) + (drop) # Reclassified (raw had it in Other because of `feat(overlay):` prefix), prefixed [Overlay]: - * feat(overlay): expose subscribeToEvents for prompt-selection (#6364) + * [Overlay] Expose `subscribeToEvents('promptSelected', …)` on `ChatOverlay` for embedders to react to in-chat prompt selection (#6364) # Security bump → Fixes, phrased as user impact: - * chore: bump axios to 1.7.9 (#6512) + * Upgrade `axios` to `1.7.9` to address CVE-2024-39338 (server-side request forgery in absolute-URL handling) (#6512) # Theme-contract change → Other with [Theme] prefix: - * chore(chat): bump dial-ui-kit to 0.20.0 (#6337) + * [Theme] Bump `@epam/ai-dial-shared` UI-kit to `0.20.0` — default button radii and disabled-state opacities shift; downstream themes overriding `--button-*` tokens may need a visual review (#6337) # Folded orphan hotfix commits into a related fix entry: - * publication URL escaping (orphan commit, no PR) - * fix tests (orphan commit, no PR) + * Escape `%` and `#` in publication URLs before they reach the router — fixes 404s on conversations with reserved characters in the title (`a1b2c3d`, `e4f5a6b`) ``` ### 6. Build the `Deployment Changes` section Add this section **only** when the range introduces at least one env-var, behavioral, or schema change. Pick subsections — include only the ones with entries: ```markdown ## Deployment Changes ### New environment variables <table: Variable | Default | Description> ### Deprecated environment variables > [!CAUTION] > Still works, but will be removed in future versions. > <table: Variable | Replacement | Description> ### Removed environment variables <table: Variable | Reason> ### New feature flags <table: Flag | Description> ### Removed feature flags <table: Flag | Reason / replacement> ### Behavioral changes > [!NOTE] > <one-line explaining the behavioral shift, e.g. preview→GA graduations> - **<Feature>** — <field / module> (#<PR>) ``` #### Which subsection: telling Behavioral and Schema deprecations apart These two look adjacent but answer different operator questions: - **Behavioral changes** — _"How does the deployed Chat app behave differently at runtime once I redeploy this image?"_ Default flag flips (e.g. a `CONFIG_DEFINITIONS` feature entry's `defaultValue` flipping to `true`), prefetch policy changes, default theme shifts, default model selection, error-handling shifts. Operator does nothing; the change is automatic on upgrade. Uses `> [!NOTE]`. - **Schema deprecations** — _"What keys in my settings JSON or overlay options payload are being renamed?"_ Inside-repo schema evolution where the parser still accepts legacy keys via aliases. Uses `> [!CAUTION]` and a table. If a change requires the operator to touch a config file outside this repo (DIAL Core's `aidial.config.json`, helm `values.yaml`, an external IDP config, an `ai-dial-chat-themes` deployment), it belongs in **DIAL Configuration changes** with a concrete remove/add migration list, never in Behavioral changes. **Crucial — what does _not_ belong here**: per-conversation settings, per-app overlay options the embedder passes at runtime, in-chat user preferences. Those changes belong in the **Features** bullet body where they're introduced. `Deployment Changes` is for operator-facing concerns: env vars, default-on/off behavioral shifts, schema-level deprecations.