scala / scala-lang

sources for the Scala language website
https://scala-lang.org
Other
274 stars 320 forks source link

"Download" and "Getting Started" pages describe disjoint realities #1183

Closed tpolecat closed 2 years ago

tpolecat commented 3 years ago

The Getting Started link (which is good) looks like a caption for the Download button (which is bad). They target pages don't even reference each other. I thought the Download page was going away ... ?

image

Anyway there needs to be exactly one (1) supported way to set up Scala and it should be cs setup. This way we can document it and support it and not leave users fumbling around. We need to go all-in on this.

tpolecat commented 3 years ago

Is there any opposition or concern about making this change? Or is it just a matter of someone doing it?

smarter commented 3 years ago

Anyway there needs to be exactly one (1) supported way to set up Scala and it should be cs setup.

I agree, but that is not guaranteed to work and fallback instructions might be needed. Here's the cs setup instructions I gave to ~250 students at EPFL this year: https://gitlab.epfl.ch/lamp/cs206/-/blob/master/labs/tools-setup.md#step-2-installing-the-java-development-kit-jdk-and-sbt-via-coursier, I refined them based on all the issues I saw students have, but even with all this some people on Windows just couldn't get it to work, I've opened several related issues:

I don't understand how people end up with such bizarrely broken systems on Windows, but it's a reality we have to deal with somehow.

julienrf commented 3 years ago

I am personally not opposed to such a change, we most probably miss someone to come up with a concrete PR.

mlachkar commented 3 years ago

In my opinion, we should first highlight “Getting started” then the “Download” page, since discovering a language is usually through a "getting started" page. And I agree that both pages should be aligned on how we install scala. I will propose a PR to fix that if you all agree.

smarter commented 3 years ago

An extra complication I seem to have missed is that cs setup will add the coursier bin directory to your PATH by editing your ~/.profile and ~/.bash_profile, but at least on some systems, this file is not sourced when starting a new shell, only when logging out and in (or rebooting), which can be pretty confusing, so it might be worth adding source ~/.profile to the instructions (except on Windows, I think restarting the terminal is enough there).

smarter commented 3 years ago

it might be worth adding source ~/.profile to the instructions

Actually that would still be confusing since if you happen to open a new terminal you wouldn't see the new PATH, maybe it's safest to ask users to reboot at that point?

smarter commented 3 years ago

I've updated https://gitlab.epfl.ch/lamp/cs206/-/blob/master/labs/tools-setup.md#step-2-installing-the-java-development-kit-jdk-and-sbt-via-coursier to ask for a reboot on linux and restarting the terminal on mac/windows (untested).

ColourGrey commented 3 years ago

Let me add, please, the genuine experience of an absolute Scala beginner (but not a computer novice!), in the hope that it might be helpful to those maintaining the web site. My system is Windows 10, 64 bit. I apologize for the length and the "half-rant" nature of my post, I wrote it in anger.

1) From the "Download" section I chose "Scala 3"; this led me to choose between a coursier installation and a sbt one. In my opinion, this is a first mistake - how would a novice know what to choose?

2) After having taken a look at the GitHub repository of Coursier, I decided to avoid it: it seems mostly a one man project (Alexandre Archambault), and one man projects die when the main maintainer gets bored, loses interest, falls ill, has a baby or gets hired and no longer has time for side projects. Furthermore, the latest successful comit dates from April 29, with the other more recent commits very few and triggering various continuous integration errors. This made me suspicious so I went with sbt.

3) I downloaded the sbt 1.5.3 installer and ran it; the installation went fine. I ran sbt from the command line, it notified me of the fact that neither build.sbt nor any project existed in the home directory, I chose to continue and...

3.1) sbt informed me that it was "getting org.scala-sbt sbt 1.5.3". Wait, wasn't I running it already? Why did it "get" it again?

3.2) Next, sbt informed me that it was "getting Scala 2.12.14 (for sbt)". Wait! I had followed the instructions on the Scala site that were guaranteed to get me running Scala 3, right? But then, why was sbt downloading 2.12.14 instead of 3? Why not 2.13.6 at least, the latest version 2 release?

3.3) And how was Scala installed: system-wide, or on a per-user basis? I don't know, I felt that the installation process was completely opaque.

4) In frustration, I chose to download the binary straight from GitHub, namely release 3.0.1-RC2. To my even greater frustration, the scala and scalac commands therein turned out to be bash scripts, totally unusable on Windows systems (I don't want to use the Linux subsystem for Windows). The GitHub binary probably comes from some alternate universe where Linux has a 73.54% market share of the worldwide desktop computing, with Windows relegated to a paltry 2.38%, otherwise I cannot explain this decision. (The Kotlin GitHub binary has both bash and ".bat" files.)

5) Both the Scala site and Wampler's "Programming Scala" mention, as the first thing to do after having installed sbt, creating a project. Really? If an absolute beginner wants to get a first taste of Scala by writing a "factorial" function, printing "Hello world" and reversing a list of integers, is the creation of a project the wisest first step to take? Isn't this a bit too intimidating? Wouldn't launching a Scala REPL, and then running the Scala compiler on a simple .scala file, be the natural first thing to learn, with projects and dependency management coming much later, and only optionally?

In conclusion, I felt that my first encounter with Scala was a total failure, and I feel that I had done my best for it not to be so. Many resources, either printed or online, notice that the pace of Scala adoption has slowed significanly during the last several years. Indeed, in the language statistics for GitHub, Scala shows up with 0.89% of the total number of pushes, and with 2.027% of the total number of pull requests. The current state of the Scala installation process is a faithful representation of this sad truth.

What was I expecting? I was expecting to be able to download an installable package, from a single site (instead of jumping among several sites), with just a few clicks, after the installation of which I would be offered a Start Menu entry that would launch the REPL - exactly what one gets after downloading Racket, Python, Ruby, Kawa Scheme, Java etc. from their respective sites. They "Just Work". With Scala, I felt like going back 25 years ago, when I was sweating over installing Linux software on my unsupported hardware of that time...

julienrf commented 2 years ago

I believe this has been fixed now that the “Download” page redirects to the “Getting Started” page.