A changelog records every change in order, release notes explain one release to the people it affects, and a "What's new" page tells a returning reader what moved since their last visit. The three differ by window, by reader and by how much they may leave out. Teams that blur them end up with one page that is too long to read and too thin to trust.
The fastest way to see the difference is to write the same change three times.
One change, three texts
Take an illustrative release of a fictional product. Its diff contains four things: the CSV export now accepts dates written DD/MM/YYYY; an empty row no longer crashes the import; the /v1/export endpoint is marked deprecated; and a dependency was bumped. Nothing here is a DeployIt feature or a customer's. It is a specimen.
The changelog entry.
2.7.0, 14 March. Added:
DD/MM/YYYYaccepted in CSV export dates. Fixed: import no longer fails on an empty row. Deprecated:/v1/export, replaced by/v2/export. Changed: parser dependency upgraded.
Four lines, all four changes, in the order and vocabulary of the code. Nothing is judged: the dependency bump sits next to the deprecation, because the record's value is that nothing is missing.
The release notes.
Dates in your exports now follow the format your team actually writes. If your file used to be rejected because of a date like 14/03/2026, it will go through. Importing a file with a blank row no longer stops the whole import. One thing to plan: the old export endpoint will be retired; integrators should move to the new one.
Three changes survive, the fourth is gone, and each one is translated into what the reader experiences. The deprecation is kept because it asks someone to act. The dependency bump is dropped because nobody outside the team can use it.
The "What's new" entry.
Exports now handle dates in day-first format.
One line, for a person who comes back every few weeks and wants to know whether the product learned something since they left. The empty row is a fix, not news. The endpoint matters to integrators, who have their own channel.
The same diff produced three correct texts. None of them is a summary of another: each one starts from the facts and applies its own rule of selection.
Reading the three side by side
What changed between the texts is not the style. It is the question each one answers.
- The changelog answers "what happened in this release?" Its reader checks a fact.
- The release notes answer "what does this release change for me?" Its reader decides whether to act.
- The "What's new" page answers "what moved since I was last here?" Its reader decides whether to come back.
Notice what that does to the window. The first two are anchored on the release: 2.7.0 is the unit. The third is anchored on the reader, so its unit is a date range that matches no tag. We cover that last case in depth in generating a "What's new" page from git; here the point is only that the three do not share a clock.
Which one do you need first?
Do not ask which is best. Ask who is already asking you questions.
- Integrators and technical customers writing in after a break. Start with the changelog, and make it dated and public. An API changelog for integrators is the specific form this takes.
- Customers and support who need to know what to tell people. Start with release notes, written once per release. Our piece on release notes your customers actually read covers the language.
- Users who return to the product and feel lost. Start with a "What's new" page, kept short on purpose.
Most teams have the first reader whether they planned it or not, and a changelog costs the least to keep accurate, because it asks for no editorial judgement. That is the argument for beginning there. It is also why it is a poor place to stop.
A common failure: the page that tries to be all three
You can spot it from the outside. It is titled "Changelog", written like marketing, and abandoned in the fourth month.
The pull is understandable. Each addition looks small: add a friendly sentence to the technical line, add a cover note on top, make it skimmable. After six months the integrator cannot find the deprecation, and the returning user cannot find the news. Both readers have been half served.
The remedy is not more care when writing. It is to keep one source of facts, the git history, and let each artefact apply its own selection rule on top. The one-source approach is what release notes for several audiences from one source describes.
Where the facts come from
Whichever you pick, the facts are already written down: in the commits and the diffs. They are dated one by one, which is exactly what the "What's new" page needs, and complete, which is what the changelog needs.
What git does not contain is the selection, and that remains a human job. DeployIt reads the real code, resynced on every push, and the git history (commits and diffs) through its own MCP servers, and checks the code before asserting anything. Read-only, revocable at any time. That makes the facts available to your docs and to your support agents; it does not decide which reader gets which sentence. The same grounding feeds a living help center and an agent-facing MCP server, which is in early access / design partner program.
Questions people ask
Can I just publish the changelog and call it done? For integrators, often yes. For a customer who does not read diffs, no: the dependency bump and the deprecation share a line, and nobody tells them which one concerns them.
Should each artefact have its own URL? Yes. A page with one job can be linked, indexed and cited without the reader having to scroll past the other two.
What if there is no change worth a line? Then the "What's new" page stays silent, the release notes say little, and the changelog still records everything. That asymmetry is the design, not a gap.
What to take away
Three artefacts, one source of facts, three rules of selection. Pick by reader, not by taste, and resist the page that serves everyone.
DeployIt is free during early access; paid plans arrive in January 2027. The MCP server is in early access / design partner program, and the program is open.
Frequently asked questions
What is the difference between a changelog, release notes and a "What's new" page?
A changelog is the complete, ordered record of changes. Release notes explain one release to the people affected by it. A "What's new" page tells a returning reader what moved since their last visit. They differ by window, by reader and by how much they are allowed to leave out.
Do I need all three?
Rarely at the start. Most teams need one source of facts and two or three presentations of it. Begin with the artefact whose reader is already asking you questions, and derive the others from the same history when the need shows up.
Can one document play all three roles?
Not well. The exhaustive record and the selective summary pull in opposite directions: the first is judged by what it misses, the second by what it spares the reader. One source can feed both; one page cannot be both.
Which one do AI agents rely on?
Whichever is public and dated. An agent asked what changed will read the most recent dated text it can reach, so a stale artefact misleads it as much as it misleads a person.
Continue reading
How do you keep developer portal content current between redesigns?
A developer portal ages page by page, not all at once. The way out: know which pages carry a fact from the code, and recompute those from the code instead of rereading them by hand.
How do you keep an engineering team's onboarding docs current?
An onboarding guide goes stale because it describes the code as it was the day it was written. Pull the facts from the code itself, and keep by hand only what no code can say.
What should an API changelog for integrators contain?
An integrator reads an API changelog to decide one thing: do I have to touch my code? Six fields answer it, and most changelogs carry two.