Announcing AnnotateRb

Annotate, also known as annotate_models, is a widely used gem that improves the Rails developer experience by automatically adding related database schema annotations to model files, as well as annotating routes in the route file. I forked it and created a new gem, AnnotateRb.

If you have seen this before in a model, then you have seen the gem in action.

Basic Rails model file with database schema annotations as comments
Database schema comments in a Rails model file

What’s different?

Improved maintainability and understandability through large refactors. Also, some of the internals have been rewritten with best practices in mind 1.

I believe it is now at a good place that it can be used as a viable replacement for the old Annotate gem. It also includes fixes for some long outstanding bugs like:

Why the fork?

The old gem is over 10 years old 2 and has not been actively maintained in years 3. Also, the codebase is in a really bad shape 4. It was hard to make significant changes with limited maintainer privileges. Forking the gem allowed me to make large scale changes to improve the project.

Curious to see some of the changes I have made? They’re available here.

There’s still a ton of work that can be done, so if you’re interested in contributing then reach out by adding issues or submitting pull requests!

P.S. I kept a log while working on the fork and plan to write more blog posts about my experience.

  1. As an example, there used to be a hard dependency on Env. The old gem would use it as a global state in many parts of the code. ↩︎

  2. ↩︎

  3. To no one’s fault. As I understand it, the owner has not actively worked in Ruby in some time now. ↩︎

  4. As an exercise, try to trace through the code path of how models get annotated when automatically run after one does bin/rails db:migrate. An entry point is here: ↩︎