I wanted to write about annual planning, and how this year is going to differ from previous ones, but I have (in true fashion) procrastinated finalizing my annual plan a little bit. So that'll be next week, and this week I would like to write about... monorepos.
Buttondown is now in a monorepo. There's two big advantages of this approach (and these advantages are not particularly new to Buttondown):
- Code sharing is much easier. I now have a lovely OpenAPI spec that powers the documentation page (and is published to its own repository, though I'll get to that in a minute); rather than having to perform a bit of a shell game keeping that spec in sync across a number of repositories, I can have a single source of truth.
- Concomitant changes are much easier. The ideal feature launch involves not just changing some stuff in the main application but writing a release note, adding a changelog entry, adding documentation — timing the release of all of these PRs was frustrating.
There are a couple downsides:
- A lot of deployment setups assume that you're trying to deploy an application at root, meaning I got to spend some time mucking around with Vercel (easy), Netlify (slightly less easy), Heroku (kind of annoying) to configure their build steps to hit the relevant subdirectory.
- A lot of tooling assumes that your configuration is stored at root. I use a lot of VS Code plugins that all helpfully assume you have a single tsconfig.json or pyproject.toml at root, which... I do not.
- My platonic ideal for Buttondown's code visibility is something like "literally everything is open source except the core application", and this is a step in the opposite direction. Even taking a fairly practical thing that I want to be open for obvious reasons, the OpenAPI spec, I now have to manually cut new PRs from the monorepo against the specific OpenAPI repository (or, more likely, set up a GitHub Action to perform the same thing). This is kind of annoying.
As you can probably tell from the benefits and drawbacks, this is...marginal. It took around five hours to finish everything (less than I expected) and I've probably recouped all of fifteen minutes' worth of effort in doing so. (Which, frankly, isn't a bad calculus if you extrapolate from a week to a year or so.)
But this is the time of year for hastily undertaking such projects! I'm trying to keep the backlog down low, but all of the "this seems nice but when am I going to have the time" type of work happens right now, in that lovely December twilight, where the roadmap doesn't matter and the sales pipeline slows down a bit.
