Archive
-
·
Psychological Safety Is the Manager's Job
A reorganisation is never a clean exercise in moving boxes. It’s a series of quiet transfers of accountability, and the consequences land on people, not charts. I learned that last year in a way I’d rather have learned second-hand.
-
·
office-stamper 3.8: Shared Headers, Once
This is a maintenance release with one headline fix and a packaging improvement.
-
·
Vermail: CJK Search with Character Bigrams
Full-text search assumes words. Chinese, Japanese and Thai don’t separate them. The default SQLite tokeniser, unicode61, splits on word boundaries, and a run of unspaced Chinese has none. A Chinese message tokenises into one enormous term, and recall collapses to 35%.
-
·
Ember字: the Study Day and Share Cards
Two unrelated things landed together.
-
·
Working Without a Reliable Internet
A few years ago I wrote about the “No Network” rule: a build that requires a steady connection is a broken build, because where I live the connection is never guaranteed. I framed it as a preference back then. It’s since become a hard requirement.
-
·
Vermail: the Sync Engine
The first decision in Vermail was that the local store is a rebuildable projection of the server, not a second source of truth. Once that’s settled, sync is just a question of asking the server for changes as cheaply as possible.
-
·
Ember字: Slimming the Decks
Decks had accumulated weight: grammar points carried notes as well as cards, and some curated entries no longer pulled their weight.
-
·
Impersonated: When a Scam Wears Your Name
In November 2025 an app appeared on a Chinese Android app store bearing my employer’s name. It invited people to invest in energy-related projects and promised elevated returns.
-
·
Ember字: the Startup Snapshot
A cold launch took 7.6 seconds: sources, dictionary, projection, then first paint. The fix was meant to be a content snapshot written on first launch and read on the next, which should have cut that to about a second and a half.
-
·
Ember字: Naming the Product and Going Proprietary
Two things got settled in September. The product got a name, Ember字, and a licence that reflects what it actually is.
-
·
Vermail: Test Against the Real Server
Unit tests tell you the code does what you told it to. They don’t tell you a mailbox is reachable, that the credentials are accepted, or that the server behaves the way its name implies. For that you need to talk to a real server.
-
·
France, Late Summer: A Late Project and a Growing Family
I went to France at the end of August. Officially it was for work, but there were really three reasons and only two of them were professional.
-
·
Vermail: Decisions Before Code
Most projects start with a feature and grow a decision trail afterwards. Vermail started the other way round. The first commits weren’t a mail client; they were a set of architecture decision records, and the build gates that would keep them honest.
-
·
Ember字: Testing on the Device with Maestro
The behaviour specs ran headless, against mocks. That catches logic errors and misses everything that only shows up on a real device: the keyboard, the soft input, the rendering, the navigation.
-
·
Ember字: Grammar Points as Cards
Grammar used to be taught by notes. ADR-0024 turns grammar points into cards, which means they enter the same review queue as everything else instead of sitting in a separate tab.
-
·
Ember字: Ordering the Review Queue by Note Type
The review queue mixed every kind of card together. A session had no rhythm: a block of grammar, then scattered vocabulary, then a review of something you hadn’t seen in weeks. You couldn’t tell what the app wanted you to do next, or why. ADR-0022 orders the queue by note type: the bucket derivation, then the drain, then the re-insertion of an again card, then the persistence of a pending card across launches.
-
·
office-stamper: Placeholders That Respect Braces
A user reported that one of his tests had changed behaviour and left a stray brace in the stamped document. The culprit was a placeholder written ${#{something} without its closing brace. The old scanner couldn’t handle it, so it left the pieces behind.
-
·
Ember字: Splitting Content from the App
The app shipped with its content baked in. The main problem was licensing: the content’s licences were tangled up with the app’s, so the corpus couldn’t ship or change on its own terms. Release cadence came a close second, because every corpus edit also meant a full app release.
-
·
Ember字: Scoping Study to the Active Level
The learner picks a level, but for a while the study session didn’t take that pick seriously. You’d declare yourself at HSK 3 and the review kept handing you words from the lowest level, the ones you hadn’t revised yet. The picker and the session could quietly draw from different pools. It felt like the app had ignored your choice.
-
·
Ember字: The Canvas v4 Design
Canvas v4 was the fourth design my partner produced, iterating back and forth with his AI tooling. It became the app’s first shipped UI. Rebuilding the screens against it was a screen-by-screen job: the Home deck picker, Settings, Words browse and detail, Statistics, the Reader lookup sheet, the study all-caught-up screen, and the onboarding flow.
-
·
Ember字: Migrating to a Monorepo
The app started as one Expo project. As it grew, review logic, content, and UI all lived in the same tree, and the boundaries started to blur. In July I split it into a pnpm + Turborepo workspace: apps/ for the mobile app and the corpus tooling, packages/ for the UI components, design tokens, the spaced-repetition core, and the content pipeline.
-
·
office-stamper: Configurable Excel Merge Strategies
Excel as a data source was already in office-stamper (I wrote about it last year). What this commit adds is that “merge the Excel data into the context” is not one operation; it’s a choice.
-
·
Founding a Company: What I Learned
In June a colleague in Beijing and I started a partnership. We called it Jing Joes. The idea was simple: AI has made a whole class of apps and services feasible that weren’t before, and we wanted to build some of them, ideally for side revenue, and at worst for ourselves.
-
·
office-stamper: The CLI Gets a Shape
office-stamper started as a library you embed. The CLI grew on top of it organically, and by June 2026 it had accreted into a Main class that did too much. Reading five hundred lines to see a workflow I already knew was the pain. A main method should read like the workflow it drives. This commit gives it that shape.
-
·
Diagrams as Code: Process, Logic, and Planning
Structure diagrams show what a system is made of. Process diagrams show what it does, in what order, and when. These are the ones I use most when the logic gets hard to hold in my head.
-
·
Monthly Topic: The AsciiDoc Modernization Journey
The AsciiDoc features in office-stamper didn’t start as a public-facing module. They emerged from a practical, internal need: developer sanity.
-
·
Diagrams as Code: Data, Sketches, and Prototypes
Not every diagram models architecture. Some of the most useful ones are quick sketches: the shape of a data structure, a regex, a GUI mockup, or a brainstorming tree. PlantUML covers these too, and they stay in plain text.
-
·
Diagrams as Code: Structure and Architecture
Architectures fail from poor visibility more often than from bad code. In one of my first jobs, a design issue ate three days of argument, and it only resolved when we drew the full application and the single possible solution finally became visible.
-
·
How-To: Diagnosing DOCX Templates with the CLI Tooling
You have a DOCX template. You run the stamper. You get a blank output, a cryptic stack trace, or a silently wrong document.
-
·
Building Trust in High-Stakes Sectors Through Craftsmanship
In high-stakes industries, trust isn’t built on promises. It’s built on verifiable evidence. Software should be held to the same standard.
-
·
Secure by Default: The CISO's Guide to Safe Templating
I’ve seen too many systems where “extensibility” is a euphemism for “security vulnerability.” When document templates let users run arbitrary expressions, that’s a disaster waiting to happen.
-
·
The Solo Maintainer's Toolbelt
Maintaining an active ecosystem of open-source projects is a challenge, but doing so while holding a full-time position in a regulated industry—where the day-to-day topics are mostly unrelated—requires a specific kind of discipline. Currently, I oversee several projects: office-stamper, the asciidoc tooling module, imageio plugins, and a custom maven-skin.
-
·
Caring Coder Manifesto: Why Governance Matters in AI
In the rush to put AI into everything, we’re losing sight of craftsmanship. For me, being a “Caring Coder” means more than passing tests. It means the governance we build around the tools that make decisions on our behalf.
-
·
Beyond the Prompt: Securing Enterprise Document Automation
Can an LLM generate a perfect .docx? Not yet, and not in a way that satisfies a CISO in a high-stakes sector like energy or finance. AI is good at synthesizing text. The structure and compliance requirements of enterprise documents are unforgiving.
-
·
Debugging $date in a Maven Skin: Old‑School Techniques Over Guesswork
Every project has that one quiet corner where something almost works. For me, it was the footer of my projects site’s Maven skin: the copyright year was hardcoded, and every time I tried to make it dynamic with $date, nothing rendered.
-
·
How‑to — ExcelContext: Expose Excel Structure to SpEL (Sheets, Cells, Tables)
This guide shows how to expose an .xlsx workbook to your templates through ExcelContext, so SpEL can query sheets, individual cells by A1 address, each sheet’s default table (header row + records), and named tables by name.
-
·
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. The constraints of limited time and unreliable networks push toward 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.