Writing about a project is easy when the project moves slowly. You can remember what changed, why a decision was made and which problem you were trying to solve. Speed creates a paradox: there is much more worth talking about and much less mental space to reconstruct the story later. In September 2026, while Blupoli was still called Blupoli Puzzles, we had reached that point. Git remembered every change. It did not automatically remember a story that would be useful to a reader.
That led to a simple idea: use the repository as a source of editorial evidence. Not to publish commits automatically, and not to turn the Devlog into a human-readable Git log, but to stop our public history from depending on memory rebuilt weeks later. The repository knows which files changed, when work was integrated and which checks accompanied it. Editorial work has to decide what those facts mean.
Git remembers facts; an article needs meaning
A commit is excellent at answering internal questions: what changed, on which branch, with which message and at what point in the timeline. An outside reader usually asks different questions. What problem existed? Why did it matter? Which alternatives failed? What changed for the product? What did we learn that remains useful beyond this one patch?
That distance between formats explains why publishing a commit history directly produces noise. A message such as “fix(i18n): normalize locale-prefixed editorial assets” is excellent for finding a technical decision. As a story, it needs context: which route broke, why the build rewrote it, how the problem was discovered and which architectural rule became clearer after the fix.
The repository is a great source and a terrible editor
Git faithfully records material that nobody needs as an article: mechanical renames, tiny copy fixes, abandoned experiments, CI adjustments and hundreds of changes that make sense only inside the tree. Its strength is precisely that it does not judge. Editorial work needs to do the opposite and select.
The workflow therefore cannot be “commit arrives, post appears.” The repository supplies raw material. Editorial review groups related changes, identifies the tension or lesson at the center and removes detail that does not help someone understand the story. Automation can reduce collection work. It should not replace the judgment of what deserves publication.
Good commit messages make storytelling easier without writing the story twice
A clear commit message is useful long before the Devlog. It helps during review, improves search, explains history to whoever is debugging a regression and gives agents better context. As a side effect, it also makes a period of development much easier to reconstruct.
That does not mean every message needs to become a miniature article. It only needs to express intent: the kind of change and the responsibility it affects. A history made of “update,” “fix stuff” and “changes” preserves the diff while losing much of the human context. A history with intent makes themes visible without opening every file.
The editorial unit rarely matches the commit unit
One visible improvement may require five commits: prepare data, change the interface, add tests, fix a review finding and update documentation. Publishing five separate stories would fragment one arc. The reverse is possible too: one large commit can contain several decisions that deserve separate explanations.
We therefore group by theme and consequence rather than hash. The repository gives us precise chronology, but the narrative can cross several commits and pull requests to explain a complete change. The useful unit is “what changed in the product or our understanding,” not “how many times did we run git commit?”
Pull requests add intent that a diff alone cannot provide
A pull request often contains a title, description, discussion, checks and the final set of changes intended for integration. That structure is valuable because it captures a broader intention than one isolated commit. It also shows which part of the work survived review.
When a branch contains several attempts, the PR helps separate experimentation from outcome. We can describe a failed approach when the failure teaches something, but we should not present every intermediate state as if it reached production. The merge is an important factual boundary.
CI gives evidence for claims about what actually happened
“We fixed it” is a stronger sentence when we can point to the checks that passed. Tests, builds, quality gates and deploys turn an editorial claim into something verifiable. An article does not need to reproduce logs, but it should preserve the distinction between code written, code verified and code actually published.
This matters even more in an AI-assisted workflow. Producing changes can be fast; demonstrating that those changes work still requires evidence. The Devlog can reflect that culture without becoming CI documentation by explaining what condition allowed us to call the work finished.
A commit date is not always the date of the story
An article can summarize several days of work. It may be published after the final PR lands or explain a decision that began earlier. Pretending one commit timestamp is the exact date of the whole story would create false precision.
What we do need is honest chronology. We should not describe a feature as available on September 10 if it was not deployed until September 14. When a story crosses stages, it helps to say what was being explored, what was under test and what reached production. Git and GitHub give us evidence to resolve those questions without relying on memory.
Automating collection is absolutely worth doing
There is a boring part of editorial work that tools handle well: list changes since the previous entry, group messages by area, find relevant PRs, surface heavily modified files and link to tests or deployments. That creates a context package for whoever writes.
The time saving is real because it removes the blank-terminal question, “What did we do this week?” The system can answer with facts. A person or editorial agent then decides whether those facts form a story about architecture, quality, design, generation or simply maintenance that does not need a public piece.
The most important filter is still “why should anyone care?”
Not every repository change that matters internally is interesting as public content. Updating a dependency, reorganizing a script or correcting a route can be essential while still failing to justify a full article. A Devlog does not need to be exhaustive.
A strong story usually contains a comprehensible tension: something stopped scaling, an abstraction failed, an assumption broke, an experiment changed direction or a small improvement revealed a larger problem. The raw material may be technical. The reason to read it should be human.
A changelog and a Devlog answer different questions
A changelog aims to tell you what was added, fixed or changed in a release. Its strengths are coverage and scanability. A Devlog can be selective and deep. It can explain why a decision was made, what path led there and which questions remain open.
Blending the two harms both. If the Devlog tries to enumerate every modification, it becomes unreadable. If the changelog narrates every trade-off, it stops being quick to scan. Git can feed both formats, but the editorial transformation should be different.
Blog and Devlog eventually became separate public surfaces
At the time of the original work we still used a mixed Journal and building-in-public structure. A few days later the editorial architecture evolved into a clearer public separation between Blog and Devlog. We describe that migration in the article about restructuring Blupoli's publishing system.
The distinction reinforces this workflow. Product news and public explainers should focus on what changed and why it matters to readers. The Devlog can go deeper into decisions, failed approaches, tools and trade-offs. Both can use Git as evidence without needing to tell the same stories in the same voice.
Failures deserve space when they change a decision
Devlog does not mean broadcasting every mistake. It means not erasing failures that explain why the system ended up the way it did. If a generation strategy produced ambiguous puzzles and that forced us to introduce solution counting, the failure is part of the useful story.
A typo fixed two minutes later probably is not. The criterion is learning. A failure belongs in the narrative when it changes the mental model, architecture or quality standard, not merely because it happened.
Reversibility can be part of the story too
Git makes experimentation less frightening because a branch can be discarded or reverted. An idea can be tested without becoming official history. That property gives us an editorial distinction between “we tried” and “we adopted.”
The difference is especially important when discussing plans. A prototype branch is not an announcement. An open PR is not a shipped feature. Repository state helps preserve those boundaries if the article respects them.
AI agents make history more important, not less
When multiple agents can research, implement and review in parallel, the rate of change rises and context fragments more quickly. History stops being only human memory. It also becomes a source that helps other agents understand earlier decisions and avoid repeating work.
AI can also create poor commit history if we do not ask for intent. A strong workflow still needs scoped tasks, clear messages, descriptive pull requests and checks. Faster production has to be matched by an equally fast ability to reconstruct why something exists.
Documentation and Git preserve different kinds of memory
The repository tells us what happened. A lasting architectural rule may deserve a document that says what should remain true in the future. Relying only on commit archaeology forces every contributor to reconstruct the reasoning again.
The Devlog adds another layer by turning selected history into public narrative. It does not replace operational documentation or technical history. All three complement each other: Git preserves evidence, docs preserve agreements and editorial publishing preserves narrated learning.
A good entry verifies its claims
If we say a new route exists, we can inspect the build. If we say a dependency disappeared, we can inspect the diff. If we say a test protects a property, we can read the test. Editorial work benefits from the same discipline as engineering: do not invent a cleaner history than the evidence supports.
This matters particularly when writing later. Memory simplifies, mixes dates and turns intentions into outcomes. The repository introduces factual friction. That friction improves the article because it forces us to distinguish what we hoped to do from what actually reached the main branch.
The diff shows the “what”; surrounding context explains the “why”
Reading only the diff tends to produce literal narration: a function was added, a selector changed, a file was renamed. To find the story we need the problem that caused those edits. Issues, tasks, PR descriptions, review comments and design notes provide that layer.
An assisted editorial workflow should collect both. Summarizing lines added and removed is not enough; the system needs the intention around them. Otherwise automation produces descriptions that are technically correct and editorially trivial.
Change volume needs windows, not infinite memory
Working within a period or milestone is useful. “Since the last entry,” “this week,” or “during the audit of this engine” creates a boundary. Without one, the collector can mix old and new work or resurface commits that were already explained.
The time window does not have to dictate publication. We can skip a week or combine periods when they form one arc. Its job is to make collection finite and prevent the entire repository history from becoming the search space every time.
Labels and conventions can suggest groups without deciding the story
Conventional Commits, area prefixes and branch names can reveal themes. Several i18n changes may belong to one localization story. Several game-engine commits may point to a broader audit. These signals are useful for a first automatic grouping.
But real stories cross categories. A UI change can originate in accessibility and end by changing architecture. Tools can propose clusters; editorial judgment decides whether those clusters actually describe the work.
Discarded commits can still explain the final result
When a branch tries two approaches and only one reaches main, the branch history can contain valuable evidence. Perhaps the first approach was too rigid, too slow or incompatible with another engine. Mentioning it can stop the final solution from looking magically obvious.
We still do not need to document every dead end. Selection remains important. We include the alternative when it clarifies a trade-off or the final decision, not because every intermediate step deserves an audience.
Automatic publishing would confuse traceability with voice
It would be technically possible to create an entry every N commits. That is exactly why choosing not to matters. Repository cadence and editorial cadence solve different problems. One intense day can produce thirty commits without a complete story; one meaningful architectural decision can take weeks before it is ready to explain.
The right automation prepares context, proposes themes and verifies facts. Publication still needs an intentional decision. That boundary stops Devlog from becoming an activity feed without hierarchy.
SEO should not decide which story exists
Once a real story has been chosen, we can absolutely improve the headline, structure and language that make it discoverable. The dangerous reversal would be mining the commit history for excuses to target a keyword. The order matters: first there is a change or lesson worth explaining, then we make it easy to find.
That keeps the Devlog useful even for someone arriving from search with no previous knowledge of Blupoli. The article should stand on its own as an explanation rather than functioning only as an internal status update.
Visual evidence can come from the product, not the diff
A diff is rarely the best illustration for readers. If a change affects navigation, a flow comparison may explain more. If it affects architecture, a layer diagram is more useful than a code screenshot. Git tells us what moved; the infographic should explain the relationship that matters.
This connects directly with our work on semantic editorial graphics: visuals should reduce the effort required to understand architecture, mechanics or before-and-after structure rather than simply breaking up the page.
History protects us from writing a perfect retrospective
Once a decision works, it is tempting to present it as inevitable. Git preserves a less elegant version: uncertainty, intermediate steps, later fixes and changes of direction. That evidence helps us write with more honesty.
We do not need to dramatize uncertainty, but we should avoid pretending the final result was obvious from the beginning. A useful Devlog shows learning. If every article turns development into perfect execution of a perfect plan, it stops functioning as development memory.
Selection should follow impact, not diff size
A three-line change can matter more than a thousand-line refactor if it changes a product guarantee. Correcting a canonical URL, introducing a generation timeout or blocking ambiguous puzzles can alter platform behavior despite a tiny diff. Counting lines is a poor way to choose stories.
Change metrics can still be signals for collection. Editorial review needs consequences: which behavior changed, which risk fell, which capability appeared or which principle became explicit. Impact produces narrative; raw volume does not.
Merges help close the factual boundary of a story
While a branch is open, its direction can still change. A merge does not guarantee perfection, but it says that one concrete version became part of the main line. For retrospective writing, that boundary keeps proposals from being mixed with results.
There is another boundary after merge: deployment. In a web product, “in main” and “published” can still be different states. A Devlog should respect that distinction just as carefully as it respects the difference between implementation and verification.
Privacy and security outrank transparency
Using Git as an editorial source does not mean exposing everything the repository contains. Secrets, personal data, security-sensitive implementation details, third-party material and internal information with no public value should stay out. Devlog is an editorial choice, not the removal of boundaries.
The context-gathering automation needs the same discipline. We do not want an agent to turn an internal name, an accidentally committed secret or sensitive detail into publication material simply because it appears in a diff. Human review remains a security boundary as well as a quality one.
Publishing a little later can make the story more accurate
Immediacy is appealing, but it is not always helpful. Waiting until a decision has passed review, integration and some real use often produces a more precise story. It can also reveal secondary effects that were invisible on the day of the first commit.
That does not prevent fast posts when there is clear news. It simply avoids turning Devlog into a requirement to narrate while we are still discovering what happened. Temporal proximity is useful; clarity matters more.
Deployment status belongs in the evidence chain
For a web product, the last useful fact is often not the merge but the deployment result. A green PR tells us that the candidate passed its checks; a successful production workflow tells us the public site actually received that candidate. When an article says “this is now live,” that final boundary matters.
Keeping deployment in the evidence chain also prevents a subtle kind of retrospective error: describing a merged change as visible when a later deploy failed. The repository, CI and hosting workflow together provide a much more reliable publication history than memory alone.
From Git to Devlog is a transformation, not an export
The workflow we still want can be summarized as four movements: collect evidence, group it by theme, edit it with judgment and publish only when a story exists. Git dominates the first step. Tools can help with the second. Editorial voice lives in the final two.
That division uses each system for what it does best. The repository is precise, exhaustive and unselective. Editorial work is selective, contextual and designed for people. Together they make Devlog possible without turning readers into commit reviewers.
The goal is memory that stays useful
Months from now, a commit will still show which line changed. A good entry can remember why that line mattered. That difference is why a Devlog remains valuable even when a project already has excellent technical history.
Blupoli will keep changing, and the editorial architecture will change with it. The principle we want to preserve is simpler: use Git as evidence, not as a substitute for narrative. That lets development move quickly without losing the ability to explain what we learned along the way.