WIP: Rework getting started documentation #11136
Conversation
|
|
||
| Play requires Java 1.8 or 1.11 and Scala 2.12 or 2.13. | ||
|
|
||
| ### Installing system and runtime dependencies |
There was a problem hiding this comment.
A suggestion for documenting the installation of scala/jdk/sbt:
I would change this to using Coursier as this will soon be the recommended way to install scala and sbt.
This is pending the release of Coursier v2.1.0
I've just tried v2.1.0-M4 and it will make installing the above a breeze.
A sample to illustrate:
$ cs install scala
https://repo1.maven.org/maven2/io/get-coursier/apps/maven-metadata.xml
No new update since 2022-02-01 23:54:11
https://repo1.maven.org/maven2/org/scala-lang/scala3-compiler_3/maven-metadata.xml
100.0% [##########] 13.0 KiB (289.9 KiB / s)
Wrote scala
$ scala
Welcome to Scala 3.1.1 (11, Java OpenJDK 64-Bit Server VM).
Type in expressions for evaluation. Or try :help.
scala>
~/Trainingen/LBT/cmt-2 on main! ⌚ 10:17:17
$ cs install scala:2.13.8
Wrote scala
~/Trainingen/LBT/cmt-2 on main! ⌚ 10:17:27
$ scala
Welcome to Scala 2.13.8 (OpenJDK 64-Bit Server VM, Java 11).
Type in expressions for evaluation. Or try :help.
scala>
:quit
Coursier can be used to install a large number of applications/tools. For a list see here.
There was a problem hiding this comment.
TIL about Coursier, I'll have a look at it and re-write this if it's a better practice over SDKMan. Thanks!
There was a problem hiding this comment.
@eloots Does the update with Coursier look right to you? I ran through the steps on my machine and it seems to work as expected.
There was a problem hiding this comment.
I don't agree 😄 SDKman is one love forever! ❤️
I'm sure it is a first and the best choice for MacOS/Linux users 🙂
But what is the best choice for Windows users I don't know 🤷♂️ I don't use Windows for more than 15 years 😱
There was a problem hiding this comment.
Agreed, SDKman is pretty cool. OTOH, Coursier works on MacOS, windows, and Linux.
But what is the best choice for Windows users I don't know
I guess that SDKman works on Windows as well, but I'm not using it either...
There was a problem hiding this comment.
Looks like we should describe two ways 😂
I think that difference is that Coursier is known more in the Scala community when SBT is a main tool. But in the Java community, SDKman is more popular, IMHO.
There was a problem hiding this comment.
Would Coursier work for people who are intending to work with play via java? We can have either SDKman or Coursier as the default and pop in a link to the other at the top. I was hoping that the Home documentation page would go from an Index of documentation to "This is how you install play and get it running" as the first thing new user sees.
Unfortunately there are a couple of paths new users can go down. So I was was hoping to consolidate as much of the getting started doco as possible.
There was a problem hiding this comment.
You can remove the instructions around cs install scala as sbt will download it for you
| ### Installing system and runtime dependencies | ||
|
|
||
| To install java and scala you can use the JVM version management tool Coursier. To install Coursier [go to the | ||
| installation instructions here](https://get-coursier.io/docs/cli-installation). Coursier will install a few |
There was a problem hiding this comment.
@Max-AR Looks good, however, I expect the installation procedures to change a bit with the release of Coursier v2.1.0.
You followed the current installation procedure which installs a version of coursier that installs a customer version of sbt. There's an issue with that: it should install the standard sbt launcher instead (as pointed out by the core maintainer of sbt (@eed3si9n)). The release of v2.1.0 should happen relatively soon, at which time we can point to the official Coursier installation instructions.
There was a problem hiding this comment.
If it is happening relatively soon I don't mind holding off until the Coursier doco is updated :) There is a fair amount to work through with this PR.
There was a problem hiding this comment.
I'll keep an eye on the Coursier release and keep you posted!
TBH, as far as I'm concerned, I don't really care about whether Coursier of SDKman (or both) are suggested.
As for Java devs, I think that Coursier works just as well.
For Scala though, Coursier offers the possibility to manage the dev environment with a single tool, which is especially great for people who are new to Scala.
There was a problem hiding this comment.
Looks good, however, I expect the installation procedures to change a bit with the release of Coursier v2.1.0
@eloots @mkurz @ihostage @BillyAutrey I have kind of mothballed this PR given that we were waiting for Couriser to reach a general release. I had a look the other day and it seems a lot more stable in it's 2.1.0-M5 release. Would we be comfortable pointing new scala users to Coursier by default in it's current state?
Between this PR and playframework/playframework.com#478, I am looking to strip out as much of the redundant or obsolete information as I can. However I think it would be good to make an exception for duplicating the setup instructions in both Coursier and SDKman give wide usage of both tools.
If we're happy to move along with Coursier as is, I'd be keen to really tighten up this PR and get it into a releasable state!
There was a problem hiding this comment.
Yeah since Coursier is in a release cycle, seems like a good time to finalize this PR.
mkurz
force-pushed
the
update-getting-started
branch
from
84e9aca to
4a58a7c
Compare
Please do not merge, looking for feedback.
Hi!
I have added a very rough first pass at reworking the "getting started" part of the documentation. This is to see what other contributors think of the direction I am taking the documentation.
The story of getting a play instance up and running is a bit rough to someone who is new to scala and play. The aim of this PR is to have a smoother experience to get someone unfamiliar with play up, running and coding as fast as possible.
I'll remove the WIP when it is completed and have received some feedback from other contributors and we are happy to merge.
Thanks!