feat: Typing for core classes in Ruby 3

[jaredcwhite]

Ruby 3 will introduce a form of type checking, using the RBS type signature language.

More info here: https://developer.squareup.com/blog/the-state-of-ruby-3-typing/

I think we have an wonderful opportunity before us to get the core classes of Bridgetown ready for Ruby 3 typing so that folks developing plugins and other extensions to Bridgetown will get code completion and other useful info in their IDEs, and we'll get a small measure of greater confidence in our code quality.

Don't misunderstand me — I am hardly an advocate for strict typing. I absolutely love Ruby's dynamic typing and don't want to do anything to move away from that center. But adding type signatures for things like Site, Document, Renderer, etc. should require minimal (if any) alterations to existing code, while at the same time allowing us to typecheck those classes and provide downstream DX enhancements.

I welcome your thoughts and feedback.

[KonnorRogers]

I love this idea. I think typing for libraries and frameworks is key to allow new users to grok what's happening without having to dig through source code. It appears it will also leverage Ruby's dynamic nature without being too stringent. I'm in full support 👍

[andrewmcodes]

I tried it and I am not a big fan to my own surprise. I thought Sorbet fell pretty short of what a good type checking solution in Ruby would be but was pretty disappointed with RBS.

In my opinion, don't reach for it until you have a pain so great you can't solve it with tests or some other tool. I think there will be a lot of churn with Ruby types so I worry about the effects it could have on maintainability if introduced here.

[jaredcwhite]

@andrewmcodes The bigger win right now is definitely to add the Yard/Solargraph comments to more classes & methods so that we get good tooltip/autocompletion in IDEs, but I'm looking forward to playing with RBS more down the road. I don't like Sorbet at all, so we're in agreement there. :)

[andrewmcodes]

I vote yard - much wider adoption

[andrewmcodes]

I have come around a bit on this. RBS is becoming more appealing as my disdain for sorbets sig methods grows 😬

[jaredcwhite]

Just adding a note here that I'm probably going to wait until there's a way to automatically generate the RBS files off of the YARD docs and go that route…I like using YARD comments and there's already an effort to beef that up across the board (#47).

[jaredcwhite]

Closing this issue for the time being – I'm not seeing the YARD > Sord > RBS pipeline moving along very quickly, so it may take some time before the ecosystem becomes more mature. In the meantime, focusing on good YARD docs and improving tests feels like the bigger win.