A changelog entry that opens with the word "we" tells the reader about the team's week instead of about their software. "We've added filters to the export screen" puts the team in the subject position and leaves the reader to translate; "Exports can now be filtered by date" puts the thing the reader controls there instead. The repair is grammatical rather than editorial. Move the feature into the subject position, delete the team from the sentence, and keep everything else about the entry as it was.
An entry that leads with "we" asks the reader to do a translation step before they learn anything. The sentence "We have improved the performance of the dashboard" carries three pieces of information — an actor, a verb and an object — and only the object matters to somebody deciding whether to open the dashboard today. The reader has to strip the actor, invert the verb, and arrive at "the dashboard is faster" on their own. Multiply that by twelve entries in a release and the changelog becomes a document people skim rather than read.
There is a second cost, and it shows up in search. A changelog page is a set of short passages, and a passage is quotable by an answer engine only when it makes sense lifted out of the page. "We've added filters" lifted out of the page is a sentence about an anonymous team. "Exports can be filtered by date range" lifted out of the page is a sentence about a product, and it names the feature somebody would actually type into a search box. Getting the subject right is the same edit for a human skimming and a machine extracting.
Rewriting an entry that leads with "we" is a fixed sequence, and it does not require rethinking what the entry says. Read the sentence, find the noun the reader can point at in the interface, and promote it to the front. The verb usually inverts on its own: "we added" becomes "is now available", "we fixed" becomes "no longer", "we improved" becomes a comparative with a number attached to it or, if there is no number, gets deleted.
Somebody deciding whether to buy your product reads the changelog for something your marketing pages cannot tell them: whether anyone is still working on it, and what happens to them when something changes.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
The table below takes four ordinary changelog lines and shows what happens when the subject moves. Nothing is added and nothing is embellished; the same fact is stated with a different noun in front. The third column is shorter than the first in every case, which is the usual side effect — the actor and the verb of doing were the padding.
| Entry as written | Subject as written | Entry rewritten |
|---|---|---|
| We've added a date filter to exports | the team | Exports can be filtered by date range |
| We fixed a bug where the sidebar collapsed on reload | the team | The sidebar no longer collapses on reload |
| We're glad to bring you dark mode | the team | Dark mode follows your system setting |
| We have improved API response times | the team | API responses are faster (no figure measured, so no figure claimed) |
The fourth row is deliberately unsatisfying. "We have improved API response times" hides the fact that nobody measured the improvement, and the rewrite exposes it. That is a feature of the edit rather than a problem with it: an entry that cannot survive losing its actor is usually an entry with nothing measurable in it, and the honest options are to measure it or to leave it out. A changelog and release notes are different documents with different obligations, and the shorter one has less room to hide.
"We" is the right subject when the actor is the news. A removal, a deprecation, a price change, a security incident and an apology are all entries where the reader's first question is who decided this, and answering it with a passive voice reads as evasion. "Support for the v1 export endpoint ends on 30 November" tells the reader what happens; "We are ending support for the v1 export endpoint on 30 November" tells the reader that a person chose it and can be asked about it. Use the actor where accountability is the point, and drop it everywhere else.
The same exception covers anything the reader has to do work about. If an entry requires a migration, a configuration change or a decision before a date, naming the team is part of naming the obligation. What it does not cover is the ordinary feature line, which is the bulk of any changelog and the place where the habit does its damage.
The entry title is the place the rule cannot be skipped, because it is often the only part a reader sees. A title is what appears in a feed reader, an email digest, a search result and a link preview, and it is read without the body underneath it. "We've shipped scheduled exports" and "Scheduled exports" carry the same fact, but only the second one works as a standalone label. Sentence case, a noun phrase, and no actor — the body can then explain the change without repeating the label.
A useful test for a changelog title is whether it would still make sense as a row in a table of contents six months later. "Improvements to the editor" fails that test twice over, because it names no feature and could describe any release. "Drafts autosave every 30 seconds" passes it, and it also happens to be the sentence somebody would search for.
No. "We" is the right subject when the actor is the news — a deprecation, a removal, a price change, a security incident or an apology. In those entries the reader's first question is who decided this, and a passive sentence reads as evasion. The habit worth breaking is using "we" for ordinary feature lines, where the actor carries no information and pushes the feature out of the subject position.
The noun the reader can point at in the interface: the screen, the field, the file, the setting or the button they touch. "Exports can be filtered by date range" names something a reader controls. "The export service now supports a date parameter" names something the builder controls. Both describe the same change, but only the first one is written from the position the reader occupies.
Either attach the measurement or remove the line. "We improved performance" survives only because the actor absorbs the vagueness; once the feature moves into the subject position the missing number is obvious. If a figure was measured, state it and say what was measured. If nothing was measured, the entry is not a changelog entry yet, and shipping it teaches readers that your changelog contains sentences with no content.
It applies to titles more strictly, because a title is read alone in feeds, email digests, search results and link previews. A title should be a sentence-case noun phrase naming the feature, with no actor and no verb of shipping. "Scheduled exports" works as a standalone label; "We've shipped scheduled exports" does not, and it wastes the first three words of a line that has very little room.
Delete the first two words and see whether the sentence still stands. "We've added a date filter to exports" becomes "a date filter to exports", which is a fragment — the entry was leaning on its actor. "Exports can be filtered by date range" survives having its first two words cut down to "can be filtered by date range", which reads as an incomplete sentence about the right subject and tells you the noun is already in front.
A changelog migration is four decisions, not a copy and paste: where the entries live from now on, what address each one answers at, what happens to the links people already shared, and who writes the next entry.
A changelog entry that links well converts better than one that sells. The rule is destination, not persuasion: link where the reader goes to use the thing, and cut every link that exists to move them somewhere you wanted them.
