Now here’s a tough problem. As a codebase grows, so does the rise...

@NotionHQ
Notion@NotionHQ
16 views Mar 05, 2025 ~2 min read
Advertisement
1
Now here’s a tough problem.
As a codebase grows, so does the rise of old code and outdated patterns. This leads to burdened engineers and large clean-up sprints.

So, we developed an open-sourced system to modernize the codebase without compromising developer speed.

But how? ⬇️
Media image
2
We all encounter the same challenge. We want our codebase to reach an ideal state—like “no more React class components”— but getting there is pretty tough.

So what do you do? We found it best to gradually migrate, or “ratchet,” older patterns over a long period of time.
3
Now, here are the four parts of our “ratcheting” system:

Lint rules: A combo of custom lint rules + publicly available lint rules that flag problems.

Baseline tracking: Maintain a database that tracks existing error counts. Treat these as temporarily acceptable while preventing new instances.
Media image
4
[Contd]
Automatic enforcement: Automatically decrease the allowed error count through pre-commit hooks. A new error? Prevent them from merging a change in the CI pipeline.

Monitoring: Mirror into Datadog + Notion to track migration progress. Phew!
Media image
5
ESLint warnings confuse developers.

Warnings pile up as they’re ignored or seen as optional, burying important issues, so we do not allow any ESLint warnings in our code.

We only allow lint rules to report as errors. If the error is specifically allowed by the ratcheting system, they are downgraded to warnings.

We love this chart:
Media image
6
Here's the ratchet file: the database that tracks lint-rule violation counts across the codebase.

So, this is what we came up with. We switched to a tab-separated value (TSV) format that keeps entries atomic + independent while keeping readability.

Each line tracks how many errors are allowed for each error combo.
Media image
7
But, but how do we know it’s working?

Well, we feed data from the ratchet file into both Notion + Datadog. This shows us how quickly we’re eliminating outdated patterns and where we might need to focus our efforts.

Integrating with Notion is super important to make the data accessible to non-engineers.
Media image
8
Traditional codemod tools like JSCodeShift require large cleanup sprints, which is pretty risky. We have successfully been able to use ESLint to codemod bad patterns away gradually.

Alright. Here’s how it works:
We first create ESLint rules to spot bad patterns. For simple violations, we write an autofixer.

For more advanced violations, we offer guidance to developers through descriptive error messages as they work around the violating code.
Media image
9
We look for just enough friction.

We found it provides just enough developer friction to uphold our high standards over time. Using the ratcheting system, we have executed many complex migrations.

Even though this makes it slightly more difficult to reorganize the codebase because we have to keep updating the ratchet file, we think this is a worthwhile trade-off.
Media image
10
The “ratcheting” system has been open sourced as eslint-seatbelt. Check it out!
github.com/justjake/eslin…

Looking for more? Dive into the details on our Tools and Crafts blog.

Read here: notion.com/blog/how-we-ev…
Media image
Actions
What You Can Do
  • Export as PDF or Markdown
  • Batch Export to Notion
  • Bookmark & Highlight
  • Screenshot Tweet
Create Free Account

Includes 7-day Premium trial

Advertisement