ai-release-notes 0.4.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -543
- package/dist/bin/cli.js +122 -25
- package/dist/bin/cli.js.map +1 -1
- package/dist/config.d.ts +5 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +19 -8
- package/dist/config.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -2
- package/dist/index.js.map +1 -1
- package/dist/output-index.d.ts +10 -3
- package/dist/output-index.d.ts.map +1 -1
- package/dist/output-index.js +154 -54
- package/dist/output-index.js.map +1 -1
- package/dist/prompt-session.d.ts +152 -25
- package/dist/prompt-session.d.ts.map +1 -1
- package/dist/prompt-session.js +1033 -68
- package/dist/prompt-session.js.map +1 -1
- package/dist/prompts/builder.d.ts +140 -1
- package/dist/prompts/builder.d.ts.map +1 -1
- package/dist/prompts/builder.js +238 -9
- package/dist/prompts/builder.js.map +1 -1
- package/dist/release.d.ts +20 -0
- package/dist/release.d.ts.map +1 -1
- package/dist/release.js +48 -0
- package/dist/release.js.map +1 -1
- package/package.json +1 -1
- package/prompts/release-prompt-session.md +361 -0
- package/prompts/release-notes-edit-system.md +0 -48
- package/prompts/release-notes-session-router.md +0 -68
- /package/prompts/{release-notes-promote-opening.md → release-promote-opening.md} +0 -0
package/README.md
CHANGED
|
@@ -2,7 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Generic AI-powered release notes generator using the [Vercel AI SDK](https://sdk.vercel.ai).
|
|
4
4
|
|
|
5
|
-
Transform your git changelog into clean, business-readable release notes — with support for OpenAI, Anthropic, Mistral, Google, Ollama, and more.
|
|
5
|
+
Transform your git changelog into clean, business-readable release notes — with support for OpenAI, Anthropic, Mistral, Google, Ollama, and more. Usable as a CLI or as a library.
|
|
6
|
+
|
|
7
|
+
- **generate** — write the notes for a version range, in Markdown and/or HTML, in one or several languages.
|
|
8
|
+
- **promote** — carry a reviewed note to the next environment, word for word.
|
|
9
|
+
- **prompt** — ask about, revise, or merge notes already written, in your own words.
|
|
6
10
|
|
|
7
11
|
**Fully customizable** via configuration: language, instructions, output format, templates, and context files.
|
|
8
12
|
|
|
@@ -39,31 +43,7 @@ API keys are **never** stored in config files. Only the key for the active provi
|
|
|
39
43
|
| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` | GPT-4o via Azure | [Get Azure credentials](docs/api-keys.md#azure-openai) |
|
|
40
44
|
| Ollama | `ollama` | None for local use; optional `OLLAMA_API_KEY` for Ollama Cloud | Local models, including Llama and Mistral | [Set up Ollama](docs/api-keys.md#ollama) |
|
|
41
45
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
**macOS / Linux:**
|
|
45
|
-
```bash
|
|
46
|
-
export OPENAI_API_KEY=sk-...
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
**Windows (PowerShell):**
|
|
50
|
-
```powershell
|
|
51
|
-
$env:OPENAI_API_KEY="sk-..."
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
**Windows (CMD):**
|
|
55
|
-
```cmd
|
|
56
|
-
set OPENAI_API_KEY=sk-...
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
**`.env` file (with dotenv):**
|
|
60
|
-
```bash
|
|
61
|
-
# Install dotenv-cli
|
|
62
|
-
npm install -g dotenv-cli
|
|
63
|
-
|
|
64
|
-
# Run with env file
|
|
65
|
-
dotenv -e .env -- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD
|
|
66
|
-
```
|
|
46
|
+
→ [Setting environment variables](docs/api-keys.md#setting-environment-variables) on macOS, Linux, Windows, or from a `.env` file.
|
|
67
47
|
|
|
68
48
|
### 2. Initialize configuration
|
|
69
49
|
|
|
@@ -71,465 +51,71 @@ dotenv -e .env -- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env
|
|
|
71
51
|
npx ai-release-notes init
|
|
72
52
|
```
|
|
73
53
|
|
|
74
|
-
This creates `.ai-release-notes.yml
|
|
54
|
+
This creates `.ai-release-notes/.ai-release-notes.yml`. **No API keys are stored in this file.**
|
|
55
|
+
A bare `.ai-release-notes.yml` at the project root, from before this was the
|
|
56
|
+
default, is still found.
|
|
75
57
|
|
|
76
58
|
### 3. Generate release notes
|
|
77
59
|
|
|
78
60
|
```bash
|
|
79
|
-
#
|
|
61
|
+
# The full Git history through v1.1.0, with the configured provider
|
|
80
62
|
npx ai-release-notes generate --to v1.1.0 --env PROD
|
|
81
63
|
|
|
82
|
-
#
|
|
83
|
-
npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD
|
|
84
|
-
|
|
85
|
-
# Uses Anthropic — needs ANTHROPIC_API_KEY
|
|
64
|
+
# One range, with Anthropic — needs ANTHROPIC_API_KEY
|
|
86
65
|
npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD --with claude
|
|
87
66
|
|
|
88
|
-
#
|
|
89
|
-
npx ai-release-notes generate --
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
The command saves files according to your configuration and reports the paths
|
|
93
|
-
it updated. To generate notes for the terminal only—without writing release
|
|
94
|
-
files or indexes—use `--stdout`. The Markdown is written to standard output;
|
|
95
|
-
status and token information go to standard error:
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
npx ai-release-notes generate --from v1.25.9 --to v1.28.0 --with mistral --env PROD --stdout
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
`--dry-run` is different: it shows the prompt without calling the AI provider.
|
|
102
|
-
Use `--verbose` to see the instruction source, main language, and configured
|
|
103
|
-
translation steps. It reports execution details, not private model reasoning.
|
|
104
|
-
|
|
105
|
-
After a generation, the command shows the provider-reported input, output,
|
|
106
|
-
and total token counts, together with the number of model calls and elapsed
|
|
107
|
-
time. Translated releases include every translation call in these totals.
|
|
108
|
-
|
|
109
|
-
## CLI Options
|
|
110
|
-
|
|
111
|
-
| Option | Description |
|
|
112
|
-
|--------|-------------|
|
|
113
|
-
| `--from <version>` | Previous version tag, or `start` for the full history (default: `start`) |
|
|
114
|
-
| `--to <version>` | Current version tag |
|
|
115
|
-
| `--env <env>` | **Required.** Environment name (PROD, STAGING, etc.) |
|
|
116
|
-
| `--date <date>` | Release date: `now` (default), `tag`, or an ISO date such as `2026-07-20` |
|
|
117
|
-
| `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
|
|
118
|
-
| `--lang <language>` | Write one configured language only (default: all of them) |
|
|
119
|
-
| `--config <path>` | Path to config file |
|
|
120
|
-
| `--output <path>` | Output file path (overrides `output.saveTo`) |
|
|
121
|
-
| `--to-dir <dir>` | Write the release into this folder (auto-names the file) |
|
|
122
|
-
| `--format <markdown\|html>` | Output format (default: `markdown`) |
|
|
123
|
-
| `--template <path>` | Custom template file |
|
|
124
|
-
| `--changelog-file <path>` | Raw changelog file (skip git) |
|
|
125
|
-
| `--context <paths...>` | Context files or directories (mixed) |
|
|
126
|
-
| `--dry-run` | Show prompts without calling LLM |
|
|
127
|
-
| `-v, --verbose` | Show applied instructions and generation steps |
|
|
128
|
-
| `--stdout` | Write generated Markdown to standard output without saving files or indexes |
|
|
129
|
-
| `--clipboard` | Copy result to clipboard |
|
|
130
|
-
|
|
131
|
-
### Release date
|
|
132
|
-
|
|
133
|
-
Use the current date (the default), the selected `--to` tag's creation date,
|
|
134
|
-
or an explicit ISO date:
|
|
135
|
-
|
|
136
|
-
```bash
|
|
137
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date now
|
|
138
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date tag
|
|
139
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date 2026-07-20
|
|
67
|
+
# Print to the terminal instead of writing release files and indexes
|
|
68
|
+
npx ai-release-notes generate --to v1.1.0 --env PROD --stdout
|
|
140
69
|
```
|
|
141
70
|
|
|
142
|
-
|
|
71
|
+
Files are saved where your configuration says, and the run reports the paths it
|
|
72
|
+
updated together with the tokens it spent.
|
|
143
73
|
|
|
144
|
-
|
|
74
|
+
→ [Generating release notes](docs/generate.md) — **CLI options**, `--dry-run`, release dates, context files.
|
|
145
75
|
|
|
146
|
-
|
|
76
|
+
### 4. Promote a release to the next environment
|
|
147
77
|
|
|
148
|
-
A
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
them again. **Promoting one release builds no prompt and calls no provider**,
|
|
152
|
-
which is also why no API key is needed:
|
|
78
|
+
A note written for QUA has already been read and agreed on. Promoting it to PROD
|
|
79
|
+
reuses those files instead of asking a model to write them again — no prompt is
|
|
80
|
+
built, no provider is called, no API key is needed:
|
|
153
81
|
|
|
154
82
|
```bash
|
|
155
83
|
# Everything PROD is missing, in one command
|
|
156
84
|
npx ai-release-notes promote --from-env QUA --to-env PROD
|
|
157
85
|
|
|
158
86
|
# Or one explicit range
|
|
159
|
-
npx ai-release-notes promote --from-env QUA --to-env PROD --from
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Each release file names the range it covers, so the files themselves form the
|
|
163
|
-
chain — `start → v0.23.0`, `v0.23.0 → v0.24.0`, and so on. Promoting reads that
|
|
164
|
-
chain rather than the version numbers, so a project that does not release in
|
|
165
|
-
ascending order is followed just as well.
|
|
166
|
-
|
|
167
|
-
- **One file covers the range** — it is promoted as it stands, word for word.
|
|
168
|
-
- **Several files cover it** — they are merged into the one note that covers
|
|
169
|
-
the whole range: sections carrying the same heading become one section,
|
|
170
|
-
their scopes become one scope, their lists become one list, and a line two
|
|
171
|
-
releases both carry is listed once. Inside a list the newest release's lines
|
|
172
|
-
come first, then the ones released before them.
|
|
173
|
-
- **A note whose shape cannot be read back** — it is never rewritten to fit.
|
|
174
|
-
The notes are kept whole and put one after another instead. Nothing to
|
|
175
|
-
choose: a note that does not survive being read and written out unchanged
|
|
176
|
-
answers this on its own.
|
|
177
|
-
|
|
178
|
-
Every section survives that merge word for word — the reviewed wording is the
|
|
179
|
-
whole point. What cannot survive it is the opening: three headings, three dates
|
|
180
|
-
and three summaries do not add up to one release note. So the merged note is
|
|
181
|
-
given a single opening, and that is the one thing a model is asked for:
|
|
182
|
-
|
|
183
|
-
```text
|
|
184
|
-
🚀 Promoting QUA → PROD: v1.25.7 → v1.28.0
|
|
185
|
-
v1.25.7 → v1.26.0
|
|
186
|
-
v1.26.0 → v1.27.0
|
|
187
|
-
v1.27.0 → v1.28.0
|
|
188
|
-
Sections merged word for word; one title and summary written for the range.
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
The model is shown the three openings and nothing else, so it cannot reach the
|
|
192
|
-
sections, and an answer that comes back carrying sections of its own is
|
|
193
|
-
refused.
|
|
194
|
-
|
|
195
|
-
When no provider is configured, when the call fails, or when the answer is
|
|
196
|
-
refused, the newest release's title and summary stand for the range instead,
|
|
197
|
-
with the environment and the version it followed pointed at what was actually
|
|
198
|
-
promoted. That is a true opening, only narrower than the range it covers, so
|
|
199
|
-
the run says so rather than reading as a success:
|
|
200
|
-
|
|
201
|
-
```text
|
|
202
|
-
⚠️ The v1.28.0 title and summary stand for the whole range: no provider is configured.
|
|
87
|
+
npx ai-release-notes promote --from-env QUA --to-env PROD --from v1.0.0 --to v1.1.0
|
|
203
88
|
```
|
|
204
89
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
newest release the source environment holds. The target environment's output
|
|
208
|
-
index is updated exactly as a generation would update it.
|
|
90
|
+
When several releases cover the range they are merged section by section, and a
|
|
91
|
+
model is asked for one thing only: the single opening that covers them all.
|
|
209
92
|
|
|
210
|
-
|
|
93
|
+
→ [Promoting a release](docs/promote.md) — **CLI options**, merge rules, environment folders.
|
|
211
94
|
|
|
212
|
-
|
|
213
|
-
layout naming its environment needs nothing else:
|
|
95
|
+
### 5. Work with existing notes
|
|
214
96
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
saveTo: ./releases/{env}/release-notes_{from}_{to}.html
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
When each environment lives in a folder that the path does not name, point at
|
|
222
|
-
the folders instead — their names become the environments:
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
npx ai-release-notes promote --from-dir ./releases/env1 --to-dir ./releases/env2
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
A `saveTo` with neither `{from}` nor `{to}` holds every release in one file
|
|
229
|
-
rather than one release per file, so there is nothing to promote from it; those
|
|
230
|
-
outputs are reported as skipped.
|
|
231
|
-
|
|
232
|
-
### Promote options
|
|
233
|
-
|
|
234
|
-
| Option | Description |
|
|
235
|
-
|--------|-------------|
|
|
236
|
-
| `--from-env <environment>` | Environment to promote from (default: `--from-dir`'s folder name) |
|
|
237
|
-
| `--to-env <environment>` | Environment to promote to (default: `--to-dir`'s folder name) |
|
|
238
|
-
| `--from <version>` | Start of the range (default: where the target environment is) |
|
|
239
|
-
| `--to <version>` | End of the range (default: the newest release in the source) |
|
|
240
|
-
| `--from-dir <dir>` / `--to-dir <dir>` | Read/write the releases in these folders |
|
|
241
|
-
| `--pattern <pattern>` | File name inside those folders (default: the configured one) |
|
|
242
|
-
| `--with <provider>` | LLM provider used to write the opening of a merged range |
|
|
243
|
-
| `--lang <language>` | Promote one language only |
|
|
244
|
-
| `--date <date>` | Release date: `now` (default), `tag`, or an ISO date |
|
|
245
|
-
| `--config <path>` | Path to config file |
|
|
246
|
-
| `--dry-run` | Show what would be promoted without writing anything |
|
|
247
|
-
| `-v, --verbose` | Show what was promoted, release by release |
|
|
248
|
-
| `--stdout` | Write the promoted notes to the terminal without saving files |
|
|
249
|
-
|
|
250
|
-
An HTML release note is read back out of the page it was written into and
|
|
251
|
-
rendered into the template again, so the promoted page states its own
|
|
252
|
-
environment, versions and date. A page written through a template this cannot
|
|
253
|
-
read is copied as it stands, which is the whole point of promoting.
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
## Asking for a change
|
|
258
|
-
|
|
259
|
-
A generated note is rarely wrong so much as not yet right: it repeats a line,
|
|
260
|
-
it says more about the build than anyone wants to read, or it drifted from your
|
|
261
|
-
own writing rules. Regenerating answers none of that — the changelog has not
|
|
262
|
-
changed, so the same note comes back and every correction already made to it is
|
|
263
|
-
lost.
|
|
264
|
-
|
|
265
|
-
`prompt` opens the notes an environment holds and asks what you would like to
|
|
266
|
-
change. You answer in your own words:
|
|
97
|
+
A generated note is rarely wrong so much as not yet right. Regenerating loses
|
|
98
|
+
every correction already made to it, so `prompt` opens an environment as a
|
|
99
|
+
release-note assistant:
|
|
267
100
|
|
|
268
101
|
```bash
|
|
269
|
-
npx ai-release-notes prompt --env
|
|
102
|
+
npx ai-release-notes prompt --env PROD
|
|
270
103
|
```
|
|
271
104
|
|
|
272
105
|
```
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
💬 Is there anything you would like to change?
|
|
278
|
-
Say it in your own words. Say you are done when you are done.
|
|
279
|
-
|
|
280
|
-
› remove the exact duplicate lines
|
|
281
|
-
› drop the technical section, I don't want to talk about the docker part
|
|
282
|
-
› group everything about "update endpoint logic" under one line
|
|
283
|
-
› format them against the project instructions again
|
|
284
|
-
› that's it, save them
|
|
106
|
+
💬 What would you like to know or change?
|
|
107
|
+
› compare the intended audience of the last two notes
|
|
108
|
+
› combine those releases and simplify the introduction
|
|
109
|
+
› save
|
|
285
110
|
```
|
|
286
111
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
Without `--from` and `--to`, every release note the environment holds is opened
|
|
293
|
-
at once, and each request is applied to all of them.
|
|
294
|
-
|
|
295
|
-
- **Nothing is written until you say so.** Each request shows what it changed,
|
|
296
|
-
line by line, and the files stay as they were until you ask for them to be
|
|
297
|
-
saved.
|
|
298
|
-
- **Repeated lines are compared, not rewritten.** Asking for exact duplicates to
|
|
299
|
-
go calls no model at all: the lines are compared here, the first of each stays
|
|
300
|
-
where you meet it, and a section left empty goes with them.
|
|
301
|
-
- **A revision changes what a note says, never which release it is**, so the
|
|
302
|
-
release index still describes it and is left alone.
|
|
303
|
-
|
|
304
|
-
### In CI
|
|
112
|
+
Ask arbitrary questions grounded in the open release files, target a particular
|
|
113
|
+
version or language, revise text, or merge a contiguous range into one note.
|
|
114
|
+
Answers are read-only. Every revision, created or deleted file, and release-index
|
|
115
|
+
update stays staged until you ask to save; undo, reset, and dry-run cover merges
|
|
116
|
+
as well. In CI, pass requests as `--ask` instead of answering them.
|
|
305
117
|
|
|
306
|
-
|
|
307
|
-
nothing to type. It saves at the end, and exits non-zero if a request failed:
|
|
308
|
-
|
|
309
|
-
```bash
|
|
310
|
-
npx ai-release-notes prompt --env PRD \
|
|
311
|
-
--ask "remove exact duplicate lines" \
|
|
312
|
-
--ask "drop any line about internal tooling" \
|
|
313
|
-
--dry-run
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
### Prompt options
|
|
317
|
-
|
|
318
|
-
| Option | Description |
|
|
319
|
-
|--------|-------------|
|
|
320
|
-
| `--env <environment>` | **Required.** Whose release notes to open |
|
|
321
|
-
| `--from <version>` / `--to <version>` | Open only the releases a range covers |
|
|
322
|
-
| `--lang <language>` | Open one language only |
|
|
323
|
-
| `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
|
|
324
|
-
| `--config <path>` | Path to config file |
|
|
325
|
-
| `--ask <request>` | Apply a request with nothing to answer. Repeatable, for CI |
|
|
326
|
-
| `--dry-run` | Show what the requests would change without writing anything |
|
|
327
|
-
| `-v, --verbose` | Show the provider and instructions the requests are answered with |
|
|
328
|
-
| `--stdout` | Write the revised notes to the terminal without saving files (needs `--ask`) |
|
|
329
|
-
|
|
330
|
-
An HTML release note is a whole page, so only the note on it is ever sent or
|
|
331
|
-
replaced: the page keeps its head, its styles, its footer, and the values the
|
|
332
|
-
template filled in when it was generated. A page whose note cannot be told apart
|
|
333
|
-
from the page around it is reported and left alone.
|
|
334
|
-
|
|
335
|
-
---
|
|
336
|
-
|
|
337
|
-
## Configuration
|
|
338
|
-
|
|
339
|
-
`.ai-release-notes.yml` describes your project and where generated files
|
|
340
|
-
belong. Keep API keys in environment variables; they are never stored in the
|
|
341
|
-
configuration file.
|
|
342
|
-
|
|
343
|
-
The main parts are simple:
|
|
344
|
-
|
|
345
|
-
- `projectName` gives the generated notes their product name.
|
|
346
|
-
- `provider` chooses the AI provider; `providers` lets you set its model and
|
|
347
|
-
generation options.
|
|
348
|
-
- `prompt` selects the release languages and where the writing rules come from.
|
|
349
|
-
See [Instructions](#instructions).
|
|
350
|
-
- `output` lists the Markdown and/or HTML release files to create. Use
|
|
351
|
-
`{env}`, `{lang}`, `{from}`, and `{to}` in their names. Missing `--from` and
|
|
352
|
-
`--to` become `start` and `end`. A name carrying `{from}` or `{to}` belongs
|
|
353
|
-
to a single release, so regenerating it rewrites that file. A name without
|
|
354
|
-
either is shared by every release, and each new one is added to it.
|
|
355
|
-
- `outputIndex` is optional. It maintains a release summary with links to
|
|
356
|
-
every release file. It may be one destination or a list, for example one
|
|
357
|
-
Markdown and one HTML summary. Add `{lang}` when each language needs its own
|
|
358
|
-
summary. `entryTemplate` sets the shape of one listed release; see
|
|
359
|
-
[Index entries](#index-entries). Index templates can place links between those
|
|
360
|
-
summaries with `{{languages}}` (or `{{langages}}`). That slot is spent the
|
|
361
|
-
first time an index is written: afterwards the switcher is found by the markup
|
|
362
|
-
it was rendered as, so a generated page carries a switcher rather than a
|
|
363
|
-
marker of ours. A single language shows no switcher at all. The switcher
|
|
364
|
-
merges languages from the current prompt with localized index files already
|
|
365
|
-
present on disk. An index template is assumed to be written in the first
|
|
366
|
-
`prompt.languages` entry, and an index in any other language is translated.
|
|
367
|
-
|
|
368
|
-
Custom instruction and summary templates are optional. The generated config
|
|
369
|
-
keeps their lines commented until you need them.
|
|
370
|
-
|
|
371
|
-
### Index entries
|
|
372
|
-
|
|
373
|
-
One listed release is one template: markup with `{{slot}}` placeholders, and
|
|
374
|
-
nothing else. The bundled one lives in
|
|
375
|
-
`templates/default-release-summary-entry.md` and `.html`:
|
|
376
|
-
|
|
377
|
-
```html
|
|
378
|
-
<section class="release-entry">
|
|
379
|
-
<h2>Release {{toVersion}}</h2>
|
|
380
|
-
<p><em>{{environment}} · {{date}} · Changes since {{fromVersion}}</em></p>
|
|
381
|
-
<p><a href="{{href}}">Read release notes</a></p>
|
|
382
|
-
</section>
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
The slots are `{{environment}}`, `{{date}}`, `{{fromVersion}}`, `{{toVersion}}`
|
|
386
|
-
and `{{href}}`. Everything else is yours to write. Point `entryTemplate` at your
|
|
387
|
-
own file to replace it:
|
|
388
|
-
|
|
389
|
-
```yaml
|
|
390
|
-
outputIndex:
|
|
391
|
-
- format: html
|
|
392
|
-
saveTo: ./releases/{env}/{lang}/index.html
|
|
393
|
-
template: ./templates/summary.html
|
|
394
|
-
entryTemplate: ./templates/entry.html
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
The entry template is read from its file on every run and translated together
|
|
398
|
-
with the summary template, so an index never carries a copy of it: editing the
|
|
399
|
-
file is what changes the shape.
|
|
400
|
-
|
|
401
|
-
Each entry stores what the index knows about its release — environment,
|
|
402
|
-
versions, date, link — in a comment marker, and the whole list is rendered again
|
|
403
|
-
on every run. Edit the entry template, or switch the index to another language,
|
|
404
|
-
and the entire history is relabelled at the next release. The list is bounded by
|
|
405
|
-
`<!-- ai-release-notes:releases -->` and `<!-- ai-release-notes:/releases -->`;
|
|
406
|
-
everything outside those two lines belongs to the summary template.
|
|
407
|
-
|
|
408
|
-
An entry that carries no record is kept word for word, below the rendered ones,
|
|
409
|
-
since there is nothing to render it from.
|
|
410
|
-
|
|
411
|
-
### The release page
|
|
412
|
-
|
|
413
|
-
An HTML release note is rendered inside `templates/default-release-note.html`,
|
|
414
|
-
and that file owns every word of the page: its `<title>`, its footer, and its
|
|
415
|
-
styles are the template's own. `--template` (or `output[].template`) points at a
|
|
416
|
-
file of yours instead. These slots are filled, and anything else is left as
|
|
417
|
-
written:
|
|
418
|
-
|
|
419
|
-
| Slot | Value |
|
|
420
|
-
|------|-------|
|
|
421
|
-
| `{{content}}` | The release note itself |
|
|
422
|
-
| `{{projectName}}` | `projectName` from the config |
|
|
423
|
-
| `{{fromVersion}}` / `{{toVersion}}` | The version range |
|
|
424
|
-
| `{{environment}}` | `--env` |
|
|
425
|
-
| `{{date}}` | The resolved release date |
|
|
426
|
-
| `{{version}}` | The `ai-release-notes` version |
|
|
427
|
-
|
|
428
|
-
A page title is a sentence, so it is written in the template's `<title>` rather
|
|
429
|
-
than assembled from the versions: there is no `{{title}}` slot.
|
|
430
|
-
|
|
431
|
-
### The first release
|
|
432
|
-
|
|
433
|
-
`--from start` — the default — reads the whole history, so there is no previous
|
|
434
|
-
version to compare against. The release note says `First release` where a
|
|
435
|
-
comparison would go, and the file name still uses `start` for `{from}`.
|
|
436
|
-
|
|
437
|
-
For the exact configuration and comments, see the annotated
|
|
438
|
-
[example `.ai-release-notes.yml`](examples/.ai-release-notes.yml). The
|
|
439
|
-
[examples guide](examples/README.md) then walks through a first run, writing
|
|
440
|
-
instructions, templates, and output layouts.
|
|
441
|
-
|
|
442
|
-
---
|
|
443
|
-
|
|
444
|
-
## Instructions
|
|
445
|
-
|
|
446
|
-
The release note is written entirely by the model: its title block, its summary,
|
|
447
|
-
and its sections all come from the instructions. Built-in instructions apply
|
|
448
|
-
until you write your own, so `generate` works with no configuration at all.
|
|
449
|
-
|
|
450
|
-
`prompt.instructions` replaces the built-in rules with your own, as inline text
|
|
451
|
-
or as a file resolved next to the config:
|
|
452
|
-
|
|
453
|
-
```yaml
|
|
454
|
-
prompt:
|
|
455
|
-
languages: [en, fr]
|
|
456
|
-
instructions:
|
|
457
|
-
file: ./.ai-release-instructions.md
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
That one file is the whole contract. A localized release goes through two
|
|
461
|
-
prompts — the first language is generated from the changelog, the others are
|
|
462
|
-
translated from it — and both receive it, so rules that matter only to one of
|
|
463
|
-
them, such as a glossary or protected vocabulary, belong in a section of the
|
|
464
|
-
same file.
|
|
465
|
-
|
|
466
|
-
The prompts themselves can be replaced too. `system` sets the role and goal
|
|
467
|
-
that precede the instructions; `user` sets how the release is described to the
|
|
468
|
-
model, through these placeholders:
|
|
469
|
-
|
|
470
|
-
```yaml
|
|
471
|
-
prompt:
|
|
472
|
-
system:
|
|
473
|
-
file: ./.ai-release-system.md
|
|
474
|
-
user: |
|
|
475
|
-
{{projectName}} {{fromVersion}} → {{toVersion}} ({{environment}}, {{date}})
|
|
476
|
-
|
|
477
|
-
{{commitCount}} commits:
|
|
478
|
-
{{changelog}}
|
|
479
|
-
{{context}}
|
|
480
|
-
```
|
|
481
|
-
|
|
482
|
-
Whatever the model receives, `--dry-run` prints it without calling a provider,
|
|
483
|
-
and `--verbose` reports which instructions were applied.
|
|
484
|
-
|
|
485
|
-
Instructions shape the release note; they do not replace it. Every request opens
|
|
486
|
-
with a scope guard that no configuration key removes, so `instructions` and
|
|
487
|
-
`system` control wording, sections, tone, language, and terminology, but cannot
|
|
488
|
-
repurpose the tool into a general-purpose assistant. See
|
|
489
|
-
[Security](#security-) for the full trust model.
|
|
490
|
-
|
|
491
|
-
---
|
|
492
|
-
|
|
493
|
-
## Context Files
|
|
494
|
-
|
|
495
|
-
Provide additional context to the LLM. Accepts a **mixed array** of files and directories:
|
|
496
|
-
|
|
497
|
-
```bash
|
|
498
|
-
npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD \
|
|
499
|
-
--context ./specs/main.md ./docs/models/ ./README.md
|
|
500
|
-
```
|
|
501
|
-
|
|
502
|
-
Context is sent to your LLM provider, so a directory scan skips what it should
|
|
503
|
-
not upload: credential-shaped files, content matching known key formats, binary
|
|
504
|
-
files, and `.git`, `.ssh`, `.aws`, `node_modules` and similar. A file you name
|
|
505
|
-
explicitly is always loaded, with a warning when it looks sensitive. Scans stop
|
|
506
|
-
at 256 KB per file, 1 MB total, 200 files, and 8 directory levels.
|
|
507
|
-
|
|
508
|
-
---
|
|
509
|
-
|
|
510
|
-
## Security 🔒
|
|
511
|
-
|
|
512
|
-
Commit messages come from anyone who can land a commit, and a config file
|
|
513
|
-
travels with the repository. Both are treated as untrusted:
|
|
514
|
-
|
|
515
|
-
- **Scope guard.** Prepended to every system prompt, including a custom
|
|
516
|
-
`prompt.system`, and not removable by configuration.
|
|
517
|
-
- **Data boundaries.** The changelog and context go to the model in labelled
|
|
518
|
-
blocks, and text imitating a delimiter is rewritten so it cannot break out.
|
|
519
|
-
- **Safe rendering.** Raw HTML in a release note is escaped and link targets are
|
|
520
|
-
limited to `http`, `https`, `mailto`, and relative paths.
|
|
521
|
-
- **Bounded spend.** `git.maxCommits` (default 200) caps one run.
|
|
522
|
-
- **Promotion.** `promote` reuses files this tool already wrote, whose markup was
|
|
523
|
-
escaped when it was generated; those files are trusted like the rest of your
|
|
524
|
-
repository. Merging several of them reaches a provider once, for the opening
|
|
525
|
-
alone: the sections are never sent, and the answer is sanitized like any other
|
|
526
|
-
model output before it reaches a page.
|
|
527
|
-
- **Endpoint checks.** `baseURL` must be `http`/`https`, and a non-local one
|
|
528
|
-
warns before any prompt leaves the machine.
|
|
529
|
-
|
|
530
|
-
A release note is still model output written from unreviewed input. Review one
|
|
531
|
-
before publishing it. Full details and reporting instructions are in
|
|
532
|
-
[security.md](security.md).
|
|
118
|
+
→ [Talking to your release notes](docs/prompt.md) — questions, merging, **CLI options**, CI mode, HTML pages.
|
|
533
119
|
|
|
534
120
|
---
|
|
535
121
|
|
|
@@ -548,106 +134,46 @@ const result = await generate({
|
|
|
548
134
|
context: ["./specs/api-v2.md", "./docs/models/"],
|
|
549
135
|
});
|
|
550
136
|
|
|
551
|
-
console.log(result.markdown);
|
|
552
|
-
console.log(result.html);
|
|
137
|
+
console.log(result.markdown, result.html);
|
|
553
138
|
```
|
|
554
139
|
|
|
555
|
-
`
|
|
556
|
-
|
|
140
|
+
`promote(options)` returns the files a promotion would write without writing
|
|
141
|
+
them, and `PromptSession` answers questions or stages revisions and merges
|
|
142
|
+
against notes already on disk, saving only when you say so.
|
|
557
143
|
|
|
558
|
-
|
|
559
|
-
markdownToHtml(markdown, { trustedHtml: true });
|
|
560
|
-
```
|
|
561
|
-
|
|
562
|
-
`promote(options)` returns the files a promotion would write, without writing
|
|
563
|
-
any of them, so you can review or publish them yourself:
|
|
564
|
-
|
|
565
|
-
```typescript
|
|
566
|
-
import { promote } from "ai-release-notes";
|
|
567
|
-
|
|
568
|
-
const { files, plan } = await promote({
|
|
569
|
-
fromEnvironment: "QUA",
|
|
570
|
-
toEnvironment: "PROD",
|
|
571
|
-
});
|
|
144
|
+
→ [Programmatic API](docs/api.md) — `generate`, `promote`, `PromptSession`, and the steps they are built from.
|
|
572
145
|
|
|
573
|
-
|
|
574
|
-
for (const file of files) {
|
|
575
|
-
console.log(file.path, "←", file.sources);
|
|
576
|
-
}
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
`PromptSession` opens the notes an environment holds and applies requests to
|
|
580
|
-
them. Nothing reaches the disk until `save`, and `callModel` lets the session
|
|
581
|
-
run on a model of your own:
|
|
582
|
-
|
|
583
|
-
```typescript
|
|
584
|
-
import { PromptSession } from "ai-release-notes";
|
|
146
|
+
---
|
|
585
147
|
|
|
586
|
-
|
|
148
|
+
## Documentation
|
|
587
149
|
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
150
|
+
| Guide | What it covers |
|
|
151
|
+
|-------|----------------|
|
|
152
|
+
| [API keys](docs/api-keys.md) | A key per provider, and where to put it |
|
|
153
|
+
| [Generating release notes](docs/generate.md) | `generate`, CLI options, dates, context files |
|
|
154
|
+
| [Promoting a release](docs/promote.md) | `promote`, merging a range, environment folders |
|
|
155
|
+
| [Talking to your release notes](docs/prompt.md) | `prompt`, questions, revisions, merges, CI mode |
|
|
156
|
+
| [Configuration](docs/configuration.md) | `.ai-release-notes.yml`, output paths, indexes, templates |
|
|
157
|
+
| [Instructions](docs/instructions.md) | What the model is told to write |
|
|
158
|
+
| [Programmatic API](docs/api.md) | Using the package as a library |
|
|
159
|
+
| [CI/CD integration](docs/ci-cd.md) | GitHub Actions, secrets, non-interactive runs |
|
|
592
160
|
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
}
|
|
161
|
+
The [example configuration](examples/.ai-release-notes.yml) is annotated, and the
|
|
162
|
+
[examples guide](examples/README.md) walks through a first run.
|
|
596
163
|
|
|
597
|
-
|
|
598
|
-
```
|
|
164
|
+
---
|
|
599
165
|
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
| Function | What it does |
|
|
603
|
-
|----------|--------------|
|
|
604
|
-
| `discoverReleases(saveTo, values)` | Read a `saveTo` pattern back off disk: which releases exist, and what their paths say about them |
|
|
605
|
-
| `formatOutputPath(saveTo, values)` | Fill `{env}`, `{lang}`, `{from}`, `{to}`; anything not supplied stays a placeholder |
|
|
606
|
-
| `planPromotion({ available, … })` | Chain release files into the run that carries one version to another |
|
|
607
|
-
| `mergeReleaseDocuments(docs, format, opts)` | Merge release notes by section and list; `leadWith: "newest"` puts the last release's lines first |
|
|
608
|
-
| `splitReleaseOpening(content, format)` | Cut a note where its first section begins: the title, date and summary on one side, the sections on the other |
|
|
609
|
-
| `dedupeReleaseDocument(content, format)` | Drop the lines a note lists twice, and report which they were |
|
|
610
|
-
| `parseReleaseDocument` / `serializeReleaseDocument` | A release note as a section tree, and back again |
|
|
611
|
-
| `extractReleaseContent(page, template?)` | Read a release note back out of the HTML page it was rendered into |
|
|
612
|
-
| `replaceReleaseContent(page, revised, template?)` | Put a revised note back on its page, leaving the page around it standing |
|
|
613
|
-
| `sanitizeReleaseHtml(html)` | Reduce model-written markup to what a release note is made of |
|
|
614
|
-
| `diffLines(before, after)` | What a revision changed, line by line |
|
|
615
|
-
| `updateOutputIndexes(params)` | Add a release to every configured index, creating the ones that do not exist |
|
|
166
|
+
## Security 🔒
|
|
616
167
|
|
|
617
|
-
|
|
168
|
+
Commit messages come from anyone who can land a commit, and a config file travels
|
|
169
|
+
with the repository. Both are treated as untrusted: a scope guard no
|
|
170
|
+
configuration key removes opens every system prompt, the changelog and context
|
|
171
|
+
reach the model in labelled blocks, model-written markup is escaped and its link
|
|
172
|
+
targets restricted, and `git.maxCommits` caps what one run can spend.
|
|
618
173
|
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
```yaml
|
|
624
|
-
name: Release Notes
|
|
625
|
-
on:
|
|
626
|
-
push:
|
|
627
|
-
tags: ["v*"]
|
|
628
|
-
|
|
629
|
-
jobs:
|
|
630
|
-
release-notes:
|
|
631
|
-
runs-on: ubuntu-latest
|
|
632
|
-
steps:
|
|
633
|
-
- uses: actions/checkout@v4
|
|
634
|
-
with:
|
|
635
|
-
fetch-depth: 0
|
|
636
|
-
|
|
637
|
-
- run: npm install -g ai-release-notes
|
|
638
|
-
|
|
639
|
-
- name: Generate
|
|
640
|
-
env:
|
|
641
|
-
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
642
|
-
run: |
|
|
643
|
-
CURRENT=${GITHUB_REF#refs/tags/}
|
|
644
|
-
PREVIOUS=$(git describe --tags --abbrev=0 ${CURRENT}^)
|
|
645
|
-
ai-release-notes generate --from $PREVIOUS --to $CURRENT --env PROD --output RELEASE_NOTES.md
|
|
646
|
-
|
|
647
|
-
- uses: softprops/action-gh-release@v1
|
|
648
|
-
with:
|
|
649
|
-
body_path: RELEASE_NOTES.md
|
|
650
|
-
```
|
|
174
|
+
A release note is still model output written from unreviewed input. Review one
|
|
175
|
+
before publishing it. Full details and reporting instructions are in
|
|
176
|
+
[security.md](security.md).
|
|
651
177
|
|
|
652
178
|
---
|
|
653
179
|
|
|
@@ -662,7 +188,7 @@ This project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md); security
|
|
|
662
188
|
|
|
663
189
|
## Community 👥
|
|
664
190
|
|
|
665
|
-
Love `ai-release-
|
|
191
|
+
Love `ai-release-notes`? Give our repo a star ⭐ ⬆️.
|
|
666
192
|
|
|
667
193
|
## License 📄
|
|
668
194
|
|