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

[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!

[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

[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