Archive
-
·
Monthly Topic — Expression Safety Patterns with Spring SpEL
In March, I pivoted office‑stamper back to Spring SpEL to unlock predictable nested contexts and fix long‑standing sharp edges. In April, we delivered SVG stamping. In May, I’m focusing on safety: how to let expressions power your templates without opening doors you don’t want opened.
-
·
How‑to — Windows Packaging for the Office‑stamper CLI (jpackage: Portable EXE + Installer)
Long‑term goal: provide a friendly command‑line that can batch‑generate documents from business‑friendly sources — Word/PowerPoint/Excel templates with data from CSV/JSON. This post documents the Windows packaging path with jpackage, plus a short note on native executable experiments.
-
·
Monthly Commit — Unifying the Image Pipeline (SVG/EMF/WMF via ImageIO)
In April, I shipped v3.3 with SVG stamping as the headline feature. This month’s commit goes deeper: I unified how office‑stamper handles images—raster and vector—by moving to a modern ImageIO‑based pipeline with custom plugins.
-
·
Office-stamper v3.3 — Vector Graphics and SVG Stamping
Following our pivot back to Spring SpEL in v3.2, version 3.3 of office-stamper addresses a request that has been on my radar for a long time: high-fidelity vector image stamping.
-
·
Back to Spring SpEL ExpressionParser
When I released office-stamper v3.0 back in January, I introduced the possibility of using a fully custom ExpressionParser. The goal was to give users complete control over how placeholders were evaluated. However, less than three months later, I am retiring that feature.
-
·
Feedback Loops and the AsciiDoc Pivot
Following the stabilization of the public surface in version 3.1, my focus for January turned toward the “engine of the engine.” As a solo maintainer, I don’t have a team to review my PRs or catch my blind spots. To maintain a professional-grade codebase, I must rely on a “Virtual Team” of automated feedback loops.
-
·
Office-stamper 3.1, Stabilizing the Surface
Following the major overhaul of v3.0, my focus for office-stamper has shifted from “making it work” to “making it stable.” Last week, I detailed how I deleted 12,000 lines of legacy test utilities. Today, I’m bringing that same pruning shears to the production engine with the release of version 3.1.
-
·
Test Suite Modernization, 12,000 Lines Lighter
As v3 of office-stamper settles in, I’ve turned my attention to the foundation that keeps the project stable: the test suite. Over the years, the test package had accumulated a significant amount of “helper” debt. This month, I’ve deleted over 12,000 lines of code, most of it redundant test utilities.
-
·
The High-Fidelity Utils Module
With the release of office-stamper v3.0, much of the spotlight has been on the new hierarchical context and the engine refactoring. However, one of the most significant changes for the long-term health of the project happened in the “ shadows”: the creation of the utils module.
-
·
Predicting the Unpredictable, The v3 Context Overhaul
Yesterday, December 14th, we officially released office-stamper v3.0.0. While the version number changed by just one digit, the architectural overhaul under the hood is the most significant since I forked the project.
-
·
Smart Tag Preprocessing, Taming Word’s Run Fragmentation
If you’ve ever used a template engine for Microsoft Word, you’ve likely encountered the “split run” nightmare. You type ${name} in Word, but internally, Word saves it as three separate XML runs: <w:r>${</w:r>, <w:r>na</w:r>, <w:r>me}</w:r>.
-
·
The Resetable Iterator, Engineering Predictable Order
As we approach the final release of office-stamper v3, the focus has shifted from “adding features” to “ensuring predictability.” One of the most significant architectural shifts in this version is how we traverse the document.
-
·
Engine Refactoring, The Road to v3
October has been a month of deep structural cleaning for office-stamper. As we approach the next major version, I’ve taken a hard look at the core engine’s abstractions. The goal is simple: make the library’s behavior more predictable for users and more maintainable for “future me.”
-
·
Hacktoberfest 2025, Engineering for the Sporadic Contributor
October is here, and with it, Hacktoberfest 2025. For office-stamper, this is not about chasing a high volume of Pull Requests. Instead, it is an invitation to join a project that is explicitly designed for the sporadic contributor.
-
·
Java 25 and the End of the LTS Wait
In August 2025, office-stamper hit a significant milestone: we are no longer waiting for the next Long-Term Support (LTS) release to move the platform forward.
-
·
The Great Documentation Offensive
As I prepare office-stamper for its version 3.0 milestone, I’ve spent much of July looking at the code not through the eyes of a developer, but through the eyes of a newcomer.
-
·
High-Fidelity Table of Contents & Google Docs Support
In the world of “docs-as-code,” we often treat Word documents as a commodity. We assume that as long as we follow the WordprocessingML (OOXML) specification, our templates will be portable across any editor.
-
·
Mutation Testing, The Truth Beyond 100% Coverage
In software engineering, we often treat 100% code coverage as a badge of honor. In a project like office-stamper, where the engine handles complex document structures and dynamic expression resolution, high coverage is a prerequisite for stability.
-
·
Beyond Stamping, A Pipeline for Document Hygiene
In document automation, generating the content is only half the battle. Once the engine has replaced placeholders and repeated rows, the resulting document often contains technical artifacts: processor comments that should be gone, orphaned footnotes, or empty paragraphs left behind by conditional logic.
-
·
Modularizing the Toolchain, The CLI/Engine Split"
For a long time, the examples module in Office-stamper served two masters: it was both a playground for users to see how to use the library, and the source of our command-line interface. As the project grew, this “cramped” arrangement started to leak. Engine-specific concerns were mixing with CLI-specific dependencies like picocli, and it was becoming too easy to accidentally depend on internal core classes that were never meant to be exported.
-
·
Monthly Commit — Beyond JSON, Using Excel as a Data Source
In my role as an IT Manager, I’m in constant contact with Finance and HR teams who live almost exclusively in Excel. While I’ve spent years advocating for “docs-as-code” and structured data like JSON or CSV, the reality is that for many stakeholders, the spreadsheet is the source of truth.
-
·
Solo Maintenance — Craftsmanship in the Downtime
Solo maintenance isn’t a day job—especially when your day job is managing IT in a different time zone. Success isn’t measured by commit frequency but by sustained changeability, and the ability to pick up exactly where you left off, whether you’re in a Beijing coffee shop or on a long commute. Embracing the constraints of limited time and unreliable networks isn’t just a survival tactic; it is a forcing function for better design.
-
·
Readable Document Testing, The Power of Characterization
In the world of document automation, we often fall into the trap of testing how instead of the what. For years, office-stamper tests were heavily focused on the underlying XML structure of WordProcessingML. We would assert that a specific w:p (paragraph) contained a specific w:r (run), and that the run had the correct w:t (text).
-
·
Normalizing Template Chaos with Pre-Processing
In November 2024, I spent a significant amount of time wrestling with “imbricated” comments—nested or overlapping comment ranges in Word documents that were causing the core stamping engine to trip over itself. Word also loves to embed proofError tags and other irrelevant XML noise that, while harmless to Word, mess up our indexing, test characterizations, and general reasoning about the document structure.
-
·
Refactoring for Contextual Clarity
In October 2024, I found myself squinting at the CommentProcessorRegistry. The engine had developed three distinct (and slightly inconsistent) ways of handling logic: inline placeholders acting as processors, processors restricted to a single paragraph, and those spanning multiple paragraphs.
-
·
Resolver Safety - Managing Nulls, Optionals, and Exception Strategies"
In document automation, your templates are more than just layouts; they are the contract between your data and your users. When a template contains ${invoice.total} or ${image(customer.photo)}, you are making a promise that the engine can fulfill that request.
-
·
Declarative Testing, Text-to-Template Generation
In the world of Office-stamper, testing has always been a heavy-duty affair. To verify a single edge case—say, how the engine preserves a tabulation character inside a run—you traditionally had to:
-
·
Mastering Nested Document Structures
In document automation, the “what you see is what you get” promise of Word often hides a complex, nested reality. This month, I addressed a long-standing limitation in how OfficeStamper perceives a paragraph. By moving from a flat traversal to a recursive approach, we’ve unlocked support for Word Form Controls and opened the door to a wider ecosystem of templates.
-
·
From Walkers to Streams
Sustainable maintenance often starts with deleting code that forces you to lie about your intentions. This month, I finally removed the CoordinatesWalker — a legacy artifact from the original docx-stamper library — and replaced it with functional streams.
-
·
Modular Reorg on the Path to 2.0
Sustainable agility depends on boundaries you can explain and defend. This month I drew those boundaries explicitly, codifying the intent I first shared in Package contracts as code.
-
·
Package contracts as code
Package‑level contracts, visible to humans and tools. I added package-info.java to state intent and enforce non‑null by default. Clear boundaries: core is internal and volatile, api is the extension surface, preset is a safe bootstrap and living examples.
-
·
PPTX Stamping Without Touching the Engine Core
PPTX stamping was added as a bounded adapter, proving the engine scales to a new format without touching the core.
-
·
Unit Tests Don’t Mean What You Think, Characterization Testing WordprocessingML in Office‑stamper
When you stamp DOCX, “unit tests” that assert on internal XML shape are a trap. WordprocessingML is a forest of paragraphs, runs, SDTs (content controls), fields, bookmarks, headers/footers, and paste‑artifacts. Tiny refactors cause harmless run splits/merges or node reordering, and brittle tests explode. Users don’t care about the exact run tree; they care that the result reads right, looks right, and keeps invariants intact.
-
·
A New Chapter in Beijing - Love, Career, and New Adventures
After 14 years together and years of separation due to pandemic restrictions, I’m finally moving to Beijing to reunite with my significant other.
-
·
Presentations as Code, Asciidoctor, Reveal.js, and Maven
I build my talks and workshops as code. The slides live in Git, are reproducible on any machine, and are published from CI with the same toolchain I run locally. The source for my decks is public:
-
·
Advent of Code, A Habit to Sharpen Algorithms and Team Energy
Every December, Advent of Code (AoC) drops two small programming puzzles each day. They are bite-sized, story‑flavored, and perfectly tuned to fit in a coffee break or an evening session. Over the years, this event has become my favorite way to keep my algorithmic muscles warm and to nudge peers into a friendly, productive competition.
-
·
Make Tests Tell a Story, Generalizing Result Descriptions"
Centralized test result descriptions across 157 test cases, replacing ad-hoc assertions with shared vocabulary. Tests now read like documentation, and failures explain what broke in business terms, not XML structures.
-
·
Hacktoberfest 2023, Office‑stamper is in
Why this post: every October, Hacktoberfest lowers the barrier for new contributors to land their first pull request. In 2023, Office‑stamper joined in with a set of small, scoped issues that improve reliability, tests, and documentation without requiring to understand the whole codebase.
-
·
Diagrams as Code; Practical Benefits in Real-World Projects"
In several of my projects, I’ve integrated Graphviz and PlantUML into the development and documentation workflows. These tools allow diagrams to be described and stored in plain text format — a practice often called Diagrams as Code.
-
·
Fewer Magic Annotations, Clearer Contracts, Removing Lombok and Aligning Javadoc
Removed Lombok and made contracts explicit in code and Javadoc. Outcome: clearer stack traces, predictable reflection, and easier onboarding for sporadic contributors.
-
·
Nextcloud self‑hosting, interests and hurdles
As a software engineer who prefers owning the tooling and data, I hosted a small Nextcloud instance on my Gandi infrastructure for my family. It let us run a truly practical shared tool without relying on a consumer SaaS. Below is a concise record of the interests that made it appealing, and the hurdles that matter if you operate it yourself.
-
·
How-to unify Test Reports across Java, Python, and TypeScript
Testing is only useful if you can trust, compare, and publish the results. This guide shows a repeatable way to generate test reports across three common stacks—Java, Python, and TypeScript—and points you to the Open Test Reporting initiative aiming to unify how we view and share results across tools.
-
·
Knowledge as a Feature, Improved Site Documentation
Docs are product. This change turns the site into a first‑class, build‑verified artifact: clearer concepts, copy‑paste examples that compile, and CI hooks so docs don’t drift.
-
·
Workshop Template for Developer Onboarding
Can a new developer build, run, and test your project in under 4 hours using only a 240-character message? This gamified workshop exposes onboarding documentation gaps through timed challenges—turning painful “where’s the docs?” conversations into an actionable improvement backlog.
-
·
Diagrams as Code in Word Templates with Office‑stamper
Keep your Word documents honest by generating diagrams from source code and stamping them at build time. Use PlantUML or Mermaid to produce images, then let Office‑stamper inject them into .docx so reports stay versioned, reproducible, and automation‑friendly.
-
·
Debugging Docx Generation with Inspectable Output
Before fixing a table cell bug, invest in the tools to understand it — this commit added debug-friendly test infrastructure, modernized code with Java 17 patterns, and built a stable assertion layer for complex WordprocessingML structures, proving that infrastructure work is feature work.
-
·
Leveling Up the Toolchain with Java 17, JUnit 5, and a Dev Container
Migrating to Java 17 LTS, JUnit 5, and a dev container to give enterprise adopters predictable builds, modern tooling, and zero-friction onboarding to the project.
-
·
Solving Nested Repeats in Word Templates
Office-stamper now supports arbitrary nesting depth for repeated document sections. A 13-line recursive fix lets templates mirror complex domain models ( school → grades → classes → students) without flattening. Includes comprehensive tests and works with existing templates.