Two Projects In A Trench Coat · The Reluctant Guide to Shopify Migrations

Tuesday standup. Zoom rectangle. The lead engineer is talking about webhook idempotency. He has been talking about webhook idempotency for four minutes and he is, by his lights, just getting started. The marketing lead’s eyes are on the bottom-right of her screen, where her inbox is open in another window, where the campaign agency has just sent her a brief with the wrong product images attached again. The CFO is muted with the camera off, on a different call entirely. You can tell because there is a small green light, two windows over, that says he is in a meeting with someone else.

The product owner is the only person listening to the lead engineer, and the product owner is listening because the product owner is the only person who is paid, in any meaningful sense, to listen to the lead engineer about webhook idempotency on a Tuesday morning.

Three conversations are happening in one Zoom rectangle. This is not unusual. This is what a replatform standup is.

Every replatform is two projects in a trench coat.

The first one is the technical project. It has artifacts. It has a Jira board. It has a Gantt chart that nobody believes but everyone references. It has commits, branches, pull requests, a staging URL with a password that is mildly humiliating. It has an architect, possibly two. It has a name for every system it touches and a diagram for every system it doesn’t. The technical project is the project the agency was hired to do. The technical project is the project on the SOW.

The second one is the organizational project, and the organizational project does not have any of those things.

The organizational project has meetings. The organizational project has the warehouse manager who you finally got on a call in week eleven, who explained—in a tone that suggested it was obvious—that returns are processed using a label format nobody at the executive level has ever heard the name of. The organizational project has the CFO who wants to see the cost savings that justified the project and has not, in his estimation, seen them yet. The organizational project has the content team who liked the old CMS, the content team who hated the old CMS, and the content team who will like the new CMS once they realize what it is, which they have not yet realized. The organizational project has the department head whose original platform choice is, by virtue of this migration, being quietly buried, and who is going to remember this in performance review season.

The organizational project has people. People with full-time jobs that the migration is, in their honest estimation, in the way of. People with departmental loyalties and political enemies and KPIs that nobody on the agency side has read. People who, when you ask them what they need, will tell you something that is true but partial—the part that is safe to say in a Zoom rectangle with eleven people in it. The other part comes out later, in a hallway, or in a Slack DM at 9:47 PM, or in the question after the question after the question, three meetings into a relationship that you had to build by accident because nobody told you it was your job.

The organizational project has no Gantt chart. It cannot have a Gantt chart. A Gantt chart for the organizational project would have a single bar that ran the full width of the project and one milestone, around week thirty-six, labeled they all start trusting each other. The bar would be the wrong color. The milestone would slip.

Two coats on wall hooks. The left coat is neat and buttoned; the right is rumpled with a loose thread pooling on the floor. — One had a Gantt chart. The other had people.

This is the book you’ve been looking for about the second project.

The first project has many books about it. The first project has the official documentation. The first project has, by our count, fourteen separate vendor-produced PDFs in circulation as we go to press, several of them quite good, all of them about the first project, none of them about what to do when the operations director stops answering your Slack messages on a Thursday.

The first project is the project everyone wants to write about, because the first project has hexagons in it, and people love a hexagon.

The second project does not have hexagons. The second project has the warehouse manager you have to call back because you forgot to ask about the label format. The second project has the head of digital who CC’d the CFO on a Friday afternoon email that he should not have CC’d the CFO on. The second project has the moment, in month five, when the operations team stops returning your messages, and you have to figure out why, and the why is not in any document. The why is in a conversation that happened in a kitchen at an offsite in 2023, two reorgs ago, about an internal tool the migration is quietly making obsolete. The why is not on the SOW. The why has never been on a SOW.

We are going to spend a big chunk of this book in the second project, because the second project is where the migrations actually go off the rails, and because the second project is the project nobody else is writing about. This is not because we find the first project uninteresting. The first project, on the contrary, fascinates us. We will go deep on middleware and search and checkout and the eighteen ways a Shopify Markets configuration can quietly betray you. We will draw architecture diagrams. We will have opinions about architecture diagrams.

But the architecture diagram is not what kills the migration. The architecture diagram is what kills the engineer, possibly, and the engineer’s weekend, and the engineer’s relationship to her partner, who has begun to wonder, around month four, whether she has been replaced by an integer field on a Shopify customer record. The architecture diagram does not, on its own, kill the migration.

Hands holding a half-unrolled blank blueprint over a desk where threads connect small everyday objects—a cup, a hinge, a key, a folded paper. — The diagram covered everything except the part that mattered.

What kills the migration is the second project.

A Brief Defense Of Why The First Project Still Matters, Despite The Foregoing

It would be irresponsible not to acknowledge that the technical project is a real project, with real difficulty, that real engineers do real, hard, good work on, and without which there would be no migration at all. There is no replatform-without-replatforming. The data has to be modeled. The webhooks have to be idempotent. (The lead engineer was right, in the standup. He just had the wrong audience.) The Hydrogen-or-Liquid question is a genuine question with a non-obvious answer, and we will spend an entire later chapter changing our minds about it.

The technical project is hard. The technical project is, in many places, hard in ways that the organizational project is not hard, which is to say: the technical project is hard in ways that yield to focused, intelligent, disciplined work by a small number of people who can be left alone in a room with a problem. This is, professionally speaking, a delight. We love the first project. The first project is the project most of us got into this business to do.

We just don’t think it is the project that wins or loses the migration. We think it is the project that makes the migration possible. We think the second project is the one that lands it.

This is also—we admit it—a self-serving distinction, because we have spent fifteen years getting good at the second project specifically, and a book that argued the first project was the whole project would be a book that argued someone else should have written it. The reader will have to weigh that bias against their own experience. We trust them to.

Senior Engineer Reading This Late at Night: you are good at the first project. We know. You would not be reading this late at night if you weren’t. The reason you are reading this late at night is not the first project. The reason you are reading this late at night is that the operations director stopped answering your Slack messages on Thursday and you don’t know what you did. The first project did not stop answering your Slack messages on Thursday. The first project does not have a Slack.

E-Commerce Director Who Skipped Lunch: you did not sign up to be a technical project manager. You signed up to be an e-commerce director. The board did not, when they approved the migration, hand you a copy of PMBOK. They handed you a budget and an implied promise that you would, in some sense, handle it. You are now discovering that handling it means, in practice, attending to the second project, and you suspect that you are not qualified to attend to the second project, and you are correct, in the sense that nobody is qualified to attend to the second project, in the sense that the second project is the kind of thing one is qualified for only retroactively. You are getting qualified now. The qualification is uncomfortable. This is normal.

Project Manager with the Gantt Chart from Hell: we’re sorry. There is no version of this migration where you are not, at least partially, a politician. The good news is that the politicians who win at this are not the ones who came in wanting to be politicians. They are the ones who came in wanting to draw a clean project plan and who slowly, reluctantly, in the middle of a long Tuesday, figured out who needed what. That is also you. You don’t know it yet.

The migrations that land well are not distinguished by a smarter technical approach or a more detailed requirements document. They are distinguished by the sustained, thankless work of keeping people aligned across months of competing priorities, shifting context, and accumulated tension. This is something we have said before, in a blog post that nobody who needed to read it read, and we are saying it again here, in a book they might actually read, because we cannot say it often enough.

Replatforms are won or lost in the messy middle. The messy middle is the second project. The rest of this book is about the second project.

We will not pretend otherwise. We will not pretend that there is a neater shape this work takes if you adopt the right framework or buy the right software. Frameworks are useful inside the second project the way maps are useful inside a country: a map tells you where the towns are, not how to get the mayor of one to talk to the mayor of another. That part you do on foot.

The first project, mercifully, is on rails.

Most of this book is about what to do when you step off them.

Here lies the migration that was, technically, on time.

The technically was doing a lot of work.