ai-release-notes 0.1.0 → 0.3.0
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 +85 -4
- package/dist/bin/cli.js +176 -195
- package/dist/bin/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +3 -0
- package/dist/config.js.map +1 -1
- package/dist/generator.d.ts +10 -0
- package/dist/generator.d.ts.map +1 -1
- package/dist/generator.js +37 -3
- package/dist/generator.js.map +1 -1
- package/dist/git.d.ts +9 -0
- package/dist/git.d.ts.map +1 -1
- package/dist/git.js +14 -1
- package/dist/git.js.map +1 -1
- package/dist/prompts/builder.d.ts.map +1 -1
- package/dist/prompts/builder.js +8 -1
- package/dist/prompts/builder.js.map +1 -1
- package/dist/release.d.ts +73 -5
- package/dist/release.d.ts.map +1 -1
- package/dist/release.js +184 -87
- package/dist/release.js.map +1 -1
- package/dist/types.d.ts +5 -5
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -1
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
- package/prompts/release-notes-instructions.md +2 -0
- package/prompts/release-notes-system.md +8 -0
- package/prompts/release-notes-translation-system.md +9 -0
- package/templates/default-release-note.html +66 -5
- package/templates/default-release-summary-entry.html +5 -0
- package/templates/default-release-summary-entry.md +5 -0
- package/templates/default-release-summary.html +7 -3
- package/templates/default-release-summary.md +1 -0
package/README.md
CHANGED
|
@@ -160,17 +160,91 @@ The main parts are simple:
|
|
|
160
160
|
See [Instructions](#instructions).
|
|
161
161
|
- `output` lists the Markdown and/or HTML release files to create. Use
|
|
162
162
|
`{env}`, `{lang}`, `{from}`, and `{to}` in their names. Missing `--from` and
|
|
163
|
-
`--to` become `start` and `end`.
|
|
163
|
+
`--to` become `start` and `end`. A name carrying `{from}` or `{to}` belongs
|
|
164
|
+
to a single release, so regenerating it rewrites that file. A name without
|
|
165
|
+
either is shared by every release, and each new one is added to it.
|
|
164
166
|
- `outputIndex` is optional. It maintains a release summary with links to
|
|
165
167
|
every release file. It may be one destination or a list, for example one
|
|
166
168
|
Markdown and one HTML summary. Add `{lang}` when each language needs its own
|
|
167
|
-
summary.
|
|
168
|
-
|
|
169
|
-
|
|
169
|
+
summary. `entryTemplate` sets the shape of one listed release; see
|
|
170
|
+
[Index entries](#index-entries). Index templates can place links between those
|
|
171
|
+
summaries with `{{languages}}` (or `{{langages}}`). That slot is spent the
|
|
172
|
+
first time an index is written: afterwards the switcher is found by the markup
|
|
173
|
+
it was rendered as, so a generated page carries a switcher rather than a
|
|
174
|
+
marker of ours. A single language shows no switcher at all. The switcher
|
|
175
|
+
merges languages from the current prompt with localized index files already
|
|
176
|
+
present on disk. An index template is assumed to be written in the first
|
|
177
|
+
`prompt.languages` entry, and an index in any other language is translated.
|
|
170
178
|
|
|
171
179
|
Custom instruction and summary templates are optional. The generated config
|
|
172
180
|
keeps their lines commented until you need them.
|
|
173
181
|
|
|
182
|
+
### Index entries
|
|
183
|
+
|
|
184
|
+
One listed release is one template: markup with `{{slot}}` placeholders, and
|
|
185
|
+
nothing else. The bundled one lives in
|
|
186
|
+
`templates/default-release-summary-entry.md` and `.html`:
|
|
187
|
+
|
|
188
|
+
```html
|
|
189
|
+
<section class="release-entry">
|
|
190
|
+
<h2>Release {{toVersion}}</h2>
|
|
191
|
+
<p><em>{{environment}} · {{date}} · Changes since {{fromVersion}}</em></p>
|
|
192
|
+
<p><a href="{{href}}">Read release notes</a></p>
|
|
193
|
+
</section>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The slots are `{{environment}}`, `{{date}}`, `{{fromVersion}}`, `{{toVersion}}`
|
|
197
|
+
and `{{href}}`. Everything else is yours to write. Point `entryTemplate` at your
|
|
198
|
+
own file to replace it:
|
|
199
|
+
|
|
200
|
+
```yaml
|
|
201
|
+
outputIndex:
|
|
202
|
+
- format: html
|
|
203
|
+
saveTo: ./releases/{env}/{lang}/index.html
|
|
204
|
+
template: ./templates/summary.html
|
|
205
|
+
entryTemplate: ./templates/entry.html
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The entry template is read from its file on every run and translated together
|
|
209
|
+
with the summary template, so an index never carries a copy of it: editing the
|
|
210
|
+
file is what changes the shape.
|
|
211
|
+
|
|
212
|
+
Each entry stores what the index knows about its release — environment,
|
|
213
|
+
versions, date, link — in a comment marker, and the whole list is rendered again
|
|
214
|
+
on every run. Edit the entry template, or switch the index to another language,
|
|
215
|
+
and the entire history is relabelled at the next release. The list is bounded by
|
|
216
|
+
`<!-- ai-release-notes:releases -->` and `<!-- ai-release-notes:/releases -->`;
|
|
217
|
+
everything outside those two lines belongs to the summary template.
|
|
218
|
+
|
|
219
|
+
An entry that carries no record is kept word for word, below the rendered ones,
|
|
220
|
+
since there is nothing to render it from.
|
|
221
|
+
|
|
222
|
+
### The release page
|
|
223
|
+
|
|
224
|
+
An HTML release note is rendered inside `templates/default-release-note.html`,
|
|
225
|
+
and that file owns every word of the page: its `<title>`, its footer, and its
|
|
226
|
+
styles are the template's own. `--template` (or `output[].template`) points at a
|
|
227
|
+
file of yours instead. These slots are filled, and anything else is left as
|
|
228
|
+
written:
|
|
229
|
+
|
|
230
|
+
| Slot | Value |
|
|
231
|
+
|------|-------|
|
|
232
|
+
| `{{content}}` | The release note itself |
|
|
233
|
+
| `{{projectName}}` | `projectName` from the config |
|
|
234
|
+
| `{{fromVersion}}` / `{{toVersion}}` | The version range |
|
|
235
|
+
| `{{environment}}` | `--env` |
|
|
236
|
+
| `{{date}}` | The resolved release date |
|
|
237
|
+
| `{{version}}` | The `ai-release-notes` version |
|
|
238
|
+
|
|
239
|
+
A page title is a sentence, so it is written in the template's `<title>` rather
|
|
240
|
+
than assembled from the versions: there is no `{{title}}` slot.
|
|
241
|
+
|
|
242
|
+
### The first release
|
|
243
|
+
|
|
244
|
+
`--from start` — the default — reads the whole history, so there is no previous
|
|
245
|
+
version to compare against. The release note says `First release` where a
|
|
246
|
+
comparison would go, and the file name still uses `start` for `{from}`.
|
|
247
|
+
|
|
174
248
|
For the exact configuration and comments, see the annotated
|
|
175
249
|
[example `.ai-release-notes.yml`](examples/.ai-release-notes.yml). The
|
|
176
250
|
[examples guide](examples/README.md) then walks through a first run, writing
|
|
@@ -284,6 +358,13 @@ console.log(result.markdown);
|
|
|
284
358
|
console.log(result.html);
|
|
285
359
|
```
|
|
286
360
|
|
|
361
|
+
`markdownToHtml(markdown, options?)` wraps Markdown in the bundled release-note
|
|
362
|
+
template, which supplies the page title and footer:
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
markdownToHtml(markdown, { trustedHtml: true });
|
|
366
|
+
```
|
|
367
|
+
|
|
287
368
|
---
|
|
288
369
|
|
|
289
370
|
## CI/CD Integration
|