Add working "get started" example #4855
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
At the moment, the "Get started" button on the homepage links to the Installation documentation, but doesn't include instructions on setting Scalafmt up for a project. It's tough to discover that there are two required pieces of configuration, and what the values of these should be. Even the configuration page (which addresses more complex examples) there's no clear of example of a minimal working config definition that teams can start from. This means Scalafmt is only accessable to engineers that already know how it works, or that have somewhere else to copy a working config file from. This change adds a note to the top of the Installation documentation, because: 1. this page is linked from "Get started" so it is the first thing people see 2. It's reasonable to interpret "Installing" to mean setting up Scalafmt on the project We use the `@STABLE_VERSION@` reference so that these docs will always point to the correct version of Scalafmt. This is especially important because there are two different versions of Scalafmt (`scalafmt-core` / `sbt-scalafmt`), which is a detail that someone just setting up IDE formatting won't need to understand.
kitbellew
requested changes
Mar 3, 2025
Comment on lines
+13
to
+14
| version = @STABLE_VERSION@ | ||
| runner.dialect = scala3 |
There was a problem hiding this comment.
- move this to the very first example in the configuration page
- mark each of these two lines there with a
# mandatorycomment - use scala213; if we are talking about complete newbies, using scala3 for 2.13 is likely to lead to very unhappy outcomes.
| @@ -5,6 +5,22 @@ title: Installation | |||
|
|
|||
| You can use Scalafmt from your editor, build tool or terminal. | |||
|
|
|||
| Create a configuration file called `.scalafmt.conf` at the root of your | |||
There was a problem hiding this comment.
replace this section with a simple
## Configuration
head and below it a link to the configuration page, possibly with a short note stressing importance of this step.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
At the moment, the "Get started" button on the homepage links to the Installation documentation, but doesn't include instructions on setting Scalafmt up for a project. I have observed that this creates significant friction for engineers that are new to Scala.
It's tough to discover that there are two required pieces of configuration, and what the values of these should be. Even on the configuration page (which addresses more complex examples) there's no clear of example of a minimal working config definition that teams can start from. This means Scalafmt is only accessible to engineers that already know how it works, or that have somewhere else to copy a working config file from.
This change adds a note to the top of the Installation documentation, because:
We use the
@STABLE_VERSION@reference so that these docs will always point to the correct version of Scalafmt. This is especially important because there are two different versions of Scalafmt (scalafmt-core/sbt-scalafmt), which is a detail that someone just setting up IDE formatting won't need to understand.I think this proposal addresses the 99% use case of someone just wanting sensible auto-formatting in their IDE and needing to fill in the required pieces of configuration without any customisation. I'm open to the idea that something like this could go on the homepage (at https://scalameta.org/scalafmt/) instead and of course, if this isn't aligned with the documentation's goals then let's chat about that instead 🙏