Keep changelogs and release notes current
Overview
Section titled “Overview”Changelogs and release notes drift the same way the rest of your docs do: they fall behind what shipped. Promptless keeps them current alongside your other docs. When a change ships, it drafts changelog entries as suggestions, following your existing changelog structure and format and the conventions you teach it.
Before drafting an entry, Promptless decides whether the change needs documentation at all. A change that touches no documented behavior produces no suggestion. See Filter noise and tune relevance for how that decision works.
This page covers pointing Promptless at your changelog, publishing changelog updates without manual review, and teaching Promptless how your entries read. To time drafts and publishing to your release stages, see Time suggestions to your release cycle.
Point Promptless at your changelog
Section titled “Point Promptless at your changelog”Where your changelog lives decides what to change:
| Where your changelog lives | What to do |
|---|---|
| In the same repository as your docs | Make sure your doc collection watches it. A collection with no folder filter watches the whole repository. |
| In a different repository from your docs | Add a separate doc collection for that repository. A repository can have only one doc collection. |
To add the changelog to an existing collection’s path scope:
-
On the Configuration page, open the Doc collections tab and open your doc collection.
-
Expand More filters (optional).
-
Under Only watch these folders, add your changelog path alongside your docs folders. The field also accepts a single file, such as
CHANGELOG.md. -
Select Save changes.
To track a changelog in another repository, select Add doc collection on the same tab. For how collections and path scope work, see Doc collections and GitHub repos (docs as code).
Publish changelog updates automatically
Section titled “Publish changelog updates automatically”Auto-merge publishes changelog entries as soon as they’re ready, with no manual review. The defaults on the Policies tab apply to every suggestion, so turning on auto-merge there also merges API reference edits and migration guides. Add a rule that applies only to your changelog instead:
-
On the Configuration page, open the Policies tab.
-
Add a rule, and under When this matches, choose the trigger that covers your changelog. If your changelog has its own doc collection, choose that collection instead.
-
Turn on Open a pull request automatically and Merge the pull request automatically. Promptless has to open a pull request before it can merge it.
-
Select Save policies.
Promptless doesn’t auto-merge into a protected branch, so branch protection on the branch Promptless targets blocks the automatic merge. For how publishing policies resolve, see Control when a suggestion publishes and the publishing policy fields.
Teach Promptless how you write changelog entries
Section titled “Teach Promptless how you write changelog entries”Promptless follows the changelog conventions you give it. Teach them through feedback or write them down:
- Keep changelog entries in their own suggestion. Feedback such as “I always want changelog entries in their own suggestion, please move” teaches this convention.
- Decide which changes deserve an entry. Where you draw that line is your team’s convention, not a setting. When you close a changelog suggestion you don’t want, choose a reason. For example, select This change is too insignificant or This change is self-explanatory and doesn’t need docs. Leave Send to Promptless checked. Or write the rule down ahead of time. See Teach Promptless what to skip for both approaches.
- Name a skill for changelog entries. In the
PROMPTLESS.mdfile in your Agent Knowledge Base, tell Promptless which skill to use when it writes changelog entries. See How Promptless learns your docs for how Promptless applies that guidance.
See also
Section titled “See also”- Time suggestions to your release cycle, to draft and publish entries at the right release stage
- GitHub commits, to start updates from commits that change your changelog
- Filter noise and tune relevance, to control which changes get suggestions