Add readme directions on migrating to Tapioca

[peternixey]

Motivation

On initially installing Tapioca I had no idea that it needed a migration in order to work from an existing Sorbet installation. This signals that need directly from the Readme

Implementation

Updated readme

Tests

n/a

[Morriar]

What do you think about moving this new section right after this one: https://github.com/Shopify/tapioca/blob/8f653b36e4529b93868cf6c07d4c359aa734baee/README.md#how-does-tapioca-compare-to-srb-rbi-gems- ?

[peternixey]

I was actually thinking exactly the same thing but didn't want to be presumptuous. Let me update the PR accordingly

[peternixey]

Hi @Morriar, I've moved the migration details into the main readme. I also tweaked a couple of other things to make it more consistent and to focus the start on the installation and the end on the details:

• two types of installation were next to each other and both termed "installation" (to discourage an exsting sorbet install to first install and then migrating - which won't work)
• the commands and flags were placed next to each other
• added a little more context to the intro at the start of the page
• moved the section on "Manual gem requires" to the bottom of the page

Apologies if the changes look confusing - I'm certain everything is in there, just re-ordered!

[Morriar]

First, thanks a lot for taking care of this. Our README desperately needed some love ❤️

I'm not sure a hard separation between fresh Sorbet project and projects using srb rbi is relevant. Many sections / steps are common to both routes and we'll end up repeating a lot of content.

What do you think about merging the two approaches but marking some steps as optional if they are related to sorbet-rails or srb rbi?

[Morriar]

Said like that it sounds like Tapioca does not provide accurate typing information contrary to other solutions?

[Morriar]

Let's put back the section ## How does tapioca compare to "srb rbi gems" ? here, before jumping to the installation procedure.

[Morriar]

Can we remove the numbering from the headers? It will make adding/removing/reordering sections more tedious.

[Morriar]

If we're going to document all of this here, we should also add a section explaining how to keep the RBIs up-to-date when the Gemfile changes and the files related to DSLs change.

[Morriar]

Let's link to the Manual gem requires section.

[Morriar]

Shouldn't all of this also be done for fresh installs?

[peternixey]

Hi @Morriar - sorry for the delayed response, I was away on holiday.

I went through your changes, all of which seemed very reasonable. I've done a complete revamp of the page here to combine the two different flows into one and then to add in the links and clarity you suggested:

https://github.com/peternixey/tapioca/blob/main/README.md

I wrote it all on the assumption that most people will find Tapioca after they find Sorbet and so the primary use-case is for an existing sorbet installation. You may know the reality of that better than me though!

BTW one thing I did was compress a lot of the text down into code blocks which I think makes it easier to scan and consume - you may feel differently though.

I also wonder whether on a document like this you might spend more time giving me kind feedback than actually doing the edits yourself. If you'd like to take the doc as it is (or as it was) and edit it however you see fit I will not be in the slightest offended and it will probably take you less time than writing me kind tweak-suggestions ;)

So let me hand this over to you and it is yours to merge / bin / use-for-inspriation as helpful!

Best wishes,
Peter

[rafaelfranca]

While I can understand a lot of users will arive to tapioca after knowing about Sorbet I think our primary flow needs to for users that didn't setup anything yet and extract the migration "guide" to a different document linked in the README.

We can still link to the document before we explain the "pristine flow" but having both flows in the same document when users will either fall in one or another category could be confusing.

[peternixey]

@rafaelfranca you guys obviously know your audience much better than me but I’m just interested in the logic as to why most people would come to Tapioca with a pristine setup.

Surely one finds out about Tapioca after trying Sorbet and then realising that it has its limitations. I could understand if Tapioca was part of the official Sorbet setup guide / package but as far as I know it’s not.

To assuage my curiosity, what’s the context in which a user would discover Tapioca prior to discovering Sorbet?

[peternixey]

I’ve just realised that of course Ruby 3 uses RBI files too so presumably that would be the other (and potentially main) use case - is that right?

[rafaelfranca]

Ruby 3 uses RBS files, not RBIs, so that is another migration setup.

To assuage my curiosity, what’s the context in which a user would discover Tapioca prior to discovering Sorbet?

Inside Shopify mostly.

But my interest of moving out the migration steps is mainly because of the perspective of the library itself. As a library, Tapioca has no knowledge on your setup, so it assumes you have a pristine setup, that is the path we mostly care about. Of course how users land here will vary, and that is fine, we should document some of those cases. I just don't think having everything in the README will make it easier to read. The README should only include the pristine way. From there we can link to other pages, sometimes maintained by different people, for the various setups that people might have before arriving here.

[peternixey]

Hi @rafaelfranca and thanks for your answers. I'd like to clarify what would be most helpful to you guys from this next. I

I'm getting conflicting messages from your side though so I'd prefer to either wrap up or hand it over. @Morriar had originally suggested combining the Sorbet-based installation with the pristine installation and so that's the way that I took it.

I'm not worried if you'd prefer to leave this but if it's helpful then there's no point in wasting the few hours that I've spent revising it. If it's a hassle tell me then I'll leave it, if it's an asset then let's make the most of the couple of hours I've spent on it so far:

Can I suggest the following course of action:

1. You tell me whether or not you'd like to tweak what I've got
2. You decide whether you'd prefer to do it or you'd like me to (for small changes it's far more sensible for you to do them)
3. You decide on one person who's code reviewing so as to avoid bouncing between different points of opinion.

FWIW I would suggest that the bulk of people outside of Shopify will find Tapioca via Sorbet so it's probably a big thing to factor into your instructions and accounting for it will hugely boost people's initial impressions of Tapioca.

I can offer you another hour of my time but only take it if you actually want this PR otherwise let's just park it.

Best
Peter

[bmulholland]

Typo: dela -> deal