Skip to content

Commit d8661a0

Browse files
authored
Merge branch 'scala:main' into zh-cn/overviews/scala3-book/taste-toplevel-definitions
2 parents 8dc4cce + 28e6fe6 commit d8661a0

16 files changed

+218
-58
lines changed

Gemfile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,4 @@ gem 'kramdown-parser-gfm'
1313
# and do:
1414
# bundle exec jekyll liveserve --incremental
1515

16-
gem "webrick", "~> 1.7"
16+
gem "webrick", "~> 1.8"

Gemfile.lock

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ GEM
7979
typhoeus (1.4.0)
8080
ethon (>= 0.9.0)
8181
unicode-display_width (1.8.0)
82-
webrick (1.7.0)
82+
webrick (1.8.1)
8383
yell (2.2.2)
8484

8585
PLATFORMS
@@ -91,7 +91,7 @@ DEPENDENCIES
9191
html-proofer
9292
jekyll-redirect-from
9393
kramdown-parser-gfm
94-
webrick (~> 1.7)
94+
webrick (~> 1.8)
9595

9696
BUNDLED WITH
9797
2.3.10

_overviews/FAQ/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,9 @@ See [this]({{ site.baseurl }}/tutorials/FAQ/initialization-order.html).
149149

150150
See the [Scala 2.13 Collections Guide](https://docs.scala-lang.org/overviews/collections-2.13/introduction.html).
151151

152-
### What are context bounds (`[T : Foo]`)?
152+
### What are context bounds?
153153

154-
It's syntactic sugar for an `implicit` parameter of type `Foo[T]`.
154+
It's syntactic sugar for a context parameter (an `implicit` parameter in Scala 2, or a `using` parameter in Scala 3).
155155

156156
More details in this [Stack Overflow answer](https://stackoverflow.com/a/4467012).
157157

_overviews/contribute/index.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,7 @@ scala_resources:
4040
icon: fa fa-bug
4141
link: /contribute/guide.html
4242
- title: Code Reviews
43-
description: "Review pull requests against scala/scala, lampepfl/dotty, scala/scala-lang, scala/docs.scala-lang,
44-
and others."
43+
description: "Review pull requests against scala/scala, lampepfl/dotty, scala/scala-lang, scala/docs.scala-lang, and others."
4544
icon: fa fa-eye
4645
link: /contribute/codereviews.html
4746
- title: Core Libraries
Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,60 @@
11
---
22
title: Context Bounds
33
type: section
4-
description: This page demonstrates Context Bounds in Scala 3.
4+
description: This page demonstrates Context Bounds in Scala.
55
languages: [zh-cn]
66
num: 61
77
previous-page: ca-given-using-clauses
88
next-page: ca-given-imports
99
---
1010

11-
12-
{% comment %}
13-
- TODO: define "context parameter"
14-
- TODO: define "synthesized" and "synthesized arguments"
15-
{% endcomment %}
16-
17-
In many situations the name of a _context parameter_ doesn’t have to be mentioned explicitly, since it’s only used by the compiler in synthesized arguments for other context parameters.
11+
In many situations the name of a [context parameter]({% link _overviews/scala3-book/ca-given-using-clauses.md %}#using-clauses) doesn’t have to be mentioned explicitly, since it’s only used by the compiler in synthesized arguments for other context parameters.
1812
In that case you don’t have to define a parameter name, and can just provide the parameter type.
1913

2014

2115
## Background
2216

2317
For example, this `maximum` method takes a _context parameter_ of type `Ord`, only to pass it on as an argument to `max`:
2418

19+
{% tabs context-bounds-max-named-param class=tabs-scala-version %}
20+
21+
{% tab 'Scala 2' %}
2522
```scala
26-
def maximum[A](xs: List[A])(using ord: Ord[A]): A =
23+
def maximum[A](xs: List[A])(implicit ord: Ord[A]): A =
2724
xs.reduceLeft(max(ord))
2825
```
26+
{% endtab %}
2927

30-
In that code the parameter name `ord` isn’t actually required; it can be passed on as an inferred argument to `max`, so you just state that `maximum` uses the type `Ord[A]` without giving it a name:
31-
28+
{% tab 'Scala 3' %}
3229
```scala
33-
def maximum[A](xs: List[A])(using Ord[A]): A =
34-
xs.reduceLeft(max)
30+
def maximum[A](xs: List[A])(using ord: Ord[A]): A =
31+
xs.reduceLeft(max(using ord))
3532
```
33+
{% endtab %}
3634

35+
{% endtabs %}
3736

3837
## Context bounds
3938

40-
Given that background, a _context bound_ is a shorthand syntax for expressing the pattern of, “a context parameter that depends on a type parameter.”
39+
Given that background, a _context bound_ is a shorthand syntax for expressing the pattern of, “a context parameter applied to a type parameter.”
4140

4241
Using a context bound, the `maximum` method can be written like this:
4342

43+
{% tabs context-bounds-max-rewritten %}
44+
45+
{% tab 'Scala 2 and 3' %}
46+
4447
```scala
45-
def maximum[A: Ord](xs: List[A]): A = xs.reduceLeft(max)
48+
def maximum[A: Ord](xs: List[A]): A =
49+
xs.reduceLeft(max)
4650
```
4751

48-
A bound like `: Ord` on a type parameter `A` of a method or class indicates a context parameter with `Ord[A]`.
52+
{% endtab %}
53+
54+
{% endtabs %}
55+
56+
57+
A bound like `: Ord` on a type parameter `A` of a method or class indicates a context parameter with type `Ord[A]`.
58+
Under the hood, the compiler transforms this syntax into the one shown in the Background section.
4959

50-
For more information about context bounds, see the [“What are context bounds?”](https://docs.scala-lang.org/tutorials/FAQ/context-bounds.html) section of the Scala FAQ.
60+
For more information about context bounds, see the [“What are context bounds?”]({% link _overviews/FAQ/index.md %}#what-are-context-bounds) section of the Scala FAQ.

_overviews/scala3-book/ca-given-imports.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,16 @@ num: 62
77
previous-page: ca-context-bounds
88
next-page: ca-type-classes
99
---
10+
<span class="tag tag-inline">Scala 3 only</span>
1011

1112

1213
To make it more clear where givens in the current scope are coming from, a special form of the `import` statement is used to import `given` instances.
1314
The basic form is shown in this example:
1415

16+
{% tabs given-imports-basic-form %}
17+
18+
{% tab 'Scala 3 Only' %}
19+
1520
```scala
1621
object A:
1722
class TC
@@ -23,15 +28,27 @@ object B:
2328
import A.given // import the given instance
2429
```
2530

31+
{% endtab %}
32+
33+
{% endtabs %}
34+
2635
In this code the `import A.*` clause of object `B` imports all members of `A` *except* the `given` instance, `tc`.
2736
Conversely, the second import, `import A.given`, imports *only* that `given` instance.
2837
The two `import` clauses can also be merged into one:
2938

39+
{% tabs given-imports-merged %}
40+
41+
{% tab 'Scala 3 Only' %}
42+
3043
```scala
3144
object B:
3245
import A.{given, *}
3346
```
3447

48+
{% endtab %}
49+
50+
{% endtabs %}
51+
3552

3653
## Discussion
3754

_overviews/scala3-book/ca-given-using-clauses.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ def renderWidget(items: List[String])(using c: Config): String = ???
6363
{% endtab %}
6464
{% endtabs %}
6565

66-
By starting a parameter section with the keyword `using`, we tell the Scala compiler that at the callsite it should automatically find an argument with the correct type.
66+
By starting a parameter section with the keyword `using`, we tell the Scala compiler that at the call-site it should automatically find an argument with the correct type.
6767
The Scala compiler thus performs **term inference**.
6868

6969
In our call to `renderWidget(List("cart"))` the Scala compiler will see that there is a term of type `Config` in scope (the `c`) and automatically provide it to `renderWidget`.

_overviews/scala3-book/ca-multiversal-equality.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,11 @@ num: 64
77
previous-page: ca-type-classes
88
next-page: ca-implicit-conversions
99
---
10+
<span class="tag tag-inline">New In Scala 3</span>
1011

12+
> Multiversal Equality is a new language feature that was introduced in Scala 3.
13+
> Because it has no equivalent in Scala 2, all code examples
14+
> in this lesson assume you are using Scala 3.
1115
1216
Previously, Scala had *universal equality*: Two values of any types could be compared with each other using `==` and `!=`.
1317
This came from the fact that `==` and `!=` are implemented in terms of Java’s `equals` method, which can also compare values of any two reference types.

_overviews/scala3-contribution/contribution-intro.md

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,26 +11,32 @@ This guide is intended to give new contributors the knowledge they need to
1111
become productive and fix issues or implement new features in Scala 3. It
1212
also documents the inner workings of the Scala 3 compiler, `dotc`.
1313

14-
### A Note on Stability
14+
### This is a living document
1515

16-
Keep in mind that the code for `dotc` is subject to change, with no
17-
guarantees of stability, so the ideas discussed in this guide may
18-
fall out of date, please consider contributing to this guide
19-
on [GitHub](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution).
16+
Keep in mind that the code for `dotc` is continually changing, so the ideas
17+
discussed in this guide may fall out of date. This is a living document, so
18+
please consider contributing to it on
19+
[GitHub](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution)
20+
if you notice anything out of date, or report any issues
21+
[here](https://github.com/scala/docs.scala-lang/issues).
2022

2123
### Get the Most from This Guide
2224

23-
`dotc` is built with Scala 3, fully utilising its [new features](/scala3/new-in-scala3.html).
24-
It is recommended that you first have some familiarity with Scala 3
25-
to get the most out of this guide. You can learn more in the [language reference]({{ site.scala3ref}}).
25+
`dotc` is built with Scala 3, fully utilising its [new
26+
features](/scala3/new-in-scala3.html). It is recommended that you first have
27+
some familiarity with Scala 3 to get the most out of this guide. You can learn
28+
more in the [language reference]({{ site.scala3ref }}).
2629

27-
Many code snippets in this guide make use of shell commands (a line beginning with `$`), and in this case
28-
a `bash` compatible shell is assumed. You may have to look up how to translate commands to your shell.
30+
Many code snippets in this guide make use of shell commands (a line beginning
31+
with `$`), and in this case a `bash` compatible shell is assumed. You may have
32+
to look up how to translate commands to your shell.
2933

3034
### What is a Compiler?
3135

32-
A compiler is a program that takes as input text, representing a program in one language
33-
and produces as output the same program, written in another programming language.
36+
Let's start at the beginning and first look at the question of "what is a
37+
compiler?". A compiler is a program that takes as input text, representing a
38+
program in one language and produces as output the same program, written in
39+
another programming language.
3440

3541
#### The Scala Compiler
3642

_overviews/scala3-contribution/procedures-checklist.md

Lines changed: 109 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,35 +7,134 @@ previous-page: procedures-testing
77
next-page: arch-intro
88
---
99

10-
Once you solved an issue, you likely want to see your change added to the [Scala 3 repo][lampepfl/dotty].
11-
To do that, you need to prepare a [pull request][pull-request] with your changes. We recommend you
12-
follow these guidelines, [also consult the full requirements][full-list]:
10+
Once you solved the issue you were working on, you'll likely want to see your
11+
changes added to the [Scala 3 repo][lampepfl/dotty]. To do that, you need to
12+
prepare a [pull request][pull-request] with your changes. Assuming that the team
13+
is aware of what you've been working, here are some final steps that you'll want
14+
to keep in mind as you create your PR.
1315

1416
### 1. Sign the CLA
1517

16-
Make sure you have signed the [Scala CLA][cla], if not, sign it.
18+
Make sure you have signed the [Scala CLA][cla]. If you have any questions about
19+
what this is and why it's required you can read further about it [here][cla].
1720

18-
### 2: Is It Relevant?
21+
### 2. Make sure your work is on its own branch
1922

20-
Before starting to work on a feature or a fix, it's good practice to ensure that:
21-
1. There is a ticket for your work in the project's [issue tracker][issues];
22-
2. The ticket has been discussed and there is desire for it to be implemented by the
23-
Scala 3 core maintainers.
23+
When submitting your pull request it's always best to ensure the branch name is
24+
unique to the changes you're working on. It's important not to submit your PR on
25+
your `main` branch as this blocks maintainers from making any changes to your PR
26+
if necessary.
2427

2528
### 3: Add Tests
29+
2630
Add at least one test that replicates the problem in the issue, and that shows it is now resolved.
2731

2832
You may of course add variations of the test code to try and eliminate edge cases.
2933
[Become familiar with testing in Scala 3][testing].
3034

3135
### 4: Add Documentation
36+
3237
Please ensure that all code is documented to explain its use, even if only internal
33-
changes are made.
38+
changes are made. This refers to scaladocs and also any changes that might be
39+
necessary in the reference docs.
40+
41+
### 5: Double check everything
42+
43+
Here are a couple tips to keep in mind.
44+
45+
- [DRY (Don't Repeat Yourself)][dry]
46+
- [Scouts Rule][scouts]
47+
- When adding new code try use [optional braces]. If you're rewriting old code,
48+
you should also use optional braces unless it introduces more code changes
49+
that necessary.
50+
51+
### 6: Commit Messages
52+
53+
Here are some guidelines when writing commits for Dotty.
54+
55+
1. If your work spans multiple local commits (for example; if you do safe point
56+
commits while working in a feature branch or work in a branch for long time
57+
doing merges/rebases etc.) then please do not commit it all but rewrite the
58+
history by squashing the commits into one large commit which is accompanied
59+
by a detailed commit message for (as discussed in the following sections).
60+
For more info, see the article: [Git Workflow][git-workflow]. Additionally,
61+
every commit should be able to be used in isolation—that is, each commit must
62+
build and pass all tests.
63+
64+
2. The first line should be a descriptive sentence about what the commit is
65+
doing. It should be possible to fully understand what the commit does by just
66+
reading this single line. It is **not ok** to only list the ticket number,
67+
type "minor fix" or similar. If the commit has a corresponding ticket,
68+
include a reference to the ticket number, prefixed with "Closes #", at the
69+
beginning of the first line followed by the title of the ticket, assuming
70+
that it aptly and concisely summarizes the commit in a single line. If the
71+
commit is a small fix, then you are done. If not, go to 3.
72+
73+
3. Following the single line description (ideally no more than 70 characters
74+
long) should be a blank line followed by an enumerated list with the details
75+
of the commit.
76+
77+
4. Add keywords for your commit (depending on the degree of automation we reach,
78+
the list may change over time):
79+
* ``Review by @githubuser`` - will notify the reviewer via GitHub. Everyone
80+
is encouraged to give feedback, however. (Remember that @-mentions will
81+
result in notifications also when pushing to a WIP branch, so please only
82+
include this in your commit message when you're ready for your pull
83+
request to be reviewed. Alternatively, you may request a review in the
84+
pull request's description.)
85+
* ``Fix/Fixing/Fixes/Close/Closing/Refs #ticket`` - if you want to mark the
86+
ticket as fixed in the issue tracker (Assembla understands this).
87+
* ``backport to _branch name_`` - if the fix needs to be cherry-picked to
88+
another branch (like 2.9.x, 2.10.x, etc)
89+
90+
Example:
91+
92+
```
93+
fix: here is your pr title briefly mentioning the topic
94+
95+
Here is the body of your pr with some more information
96+
- Details 1
97+
- Details 2
98+
- Details 3
99+
100+
Closes #2
101+
```
102+
103+
### 7: Create your PR!
104+
105+
When the feature or fix is completed you should open a [Pull
106+
Request](https://help.github.com/articles/using-pull-requests) on GitHub.
107+
108+
If you're not actually finished yet and are just looking for some initial input
109+
on your approach, feel free to open a [Draft PR][draft]. This lets reviewers
110+
know that you're not finished yet. It's also a good idea to put a [wip] in front
111+
of your pr title to make this extra clear.
112+
113+
Shortly after creating your pull request a maintainer should assign someone to
114+
review it. If this doesn't happen after a few days, feel free to ping someone on
115+
the [Scala Contributors Discor][discord] or tag someone on the PR. Depending on
116+
the type of pull request there might be multiple people that take a look at your
117+
changes. There might also be community input as we try to keep the review
118+
process as open as possible.
119+
120+
### 8: Addressing feedback
121+
122+
More than likely you'll get feedback from the reviewers, so you'll want to make
123+
sure to address everything. When in doubt, don't hesitate to ask for
124+
clarification or more information.
34125

126+
Once you finally see the "LGTM" (Looks Good To Me or Let's Get This Merged)
127+
you're PR will be merged in!
35128

36129
[pull-request]: https://docs.github.com/en?query=pull+requests
37130
[lampepfl/dotty]: https://github.com/lampepfl/dotty
38131
[cla]: http://typesafe.com/contribute/cla/scala
39132
[issues]: https://github.com/lampepfl/dotty/issues
40133
[full-list]: https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md
41134
[testing]: {% link _overviews/scala3-contribution/procedures-testing.md %}
135+
[discord]: https://discord.gg/TSmY9zkHar
136+
[dry]: https://www.oreilly.com/library/view/97-things-every/9780596809515/ch30.html
137+
[scouts]: https://www.oreilly.com/library/view/97-things-every/9780596809515/ch08.html
138+
[optional-braces]: https://docs.scala-lang.org/scala3/reference/other-new-features/indentation.html
139+
[draft]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
140+
[git-workflow]: http://sandofsky.com/blog/git-workflow.html

0 commit comments

Comments
 (0)