From cd37d072bfb9a240e96ed6ae19daecb086317043 Mon Sep 17 00:00:00 2001 From: Jake Zimmerman Date: Tue, 23 Apr 2024 13:48:03 -0500 Subject: [PATCH] Add note about `include T::Sig` monkey patch (#7850) --- website/docs/sigs.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/website/docs/sigs.md b/website/docs/sigs.md index 84dda95df7c..74e13a26188 100644 --- a/website/docs/sigs.md +++ b/website/docs/sigs.md @@ -350,3 +350,45 @@ calls: `T.let` and `T.cast` to do type refinements and assertions are central to Sorbet being a gradual type system). Since types must already be valid Ruby, it makes sense to have `sig`s be valid Ruby too. + +## Can I skip writing `extend T::Sig` everywhere? + +To skip writing `extend T::Sig` inside every class that wants to use `sig`, use +this monkey patch: + +```ruby +class Module + include T::Sig +end +``` + +Since every singleton class descends from `Module`, this will make the `sig` +method available in every class body. + +This involves a monkey patch, and is **not** required to use Sorbet. But the +most earnest users of Sorbet all eventually add this monkey patch, because +`extend T::Sig` ends up getting written into almost every class. + +We recommend putting this monkeypatch in the same file that + +- requires `sorbet-runtime`, and +- sets up any [`T::Configuration`](tconfiguration.md) `sorbet-runtime` + configurations + +So that it's impossible to get one of these three things without the others. + +The upside: + +- Drops the "activation energy" required to add the first `sig` to a class. + Simply start writing `sig` above the current method. + +- Fewer lines dedicated to type annotations. + +The downside: + +- Adds a monkey patch to a Ruby standard library class, which might conflict + with other methods defined by the current project or its gems. + +- If users have _only_ required `sorbet-runtime` and forgotten to require the + file defining this monkey patch, the code can fail at runtime in unexpected + ways.