From 0213845da1460dddc1d5171cd8c8628fbc93610c Mon Sep 17 00:00:00 2001 From: Anatolii Kmetiuk Date: Wed, 1 Jun 2022 12:07:52 +0200 Subject: [PATCH 1/8] Add Scala for Java Programmers article --- index.md | 8 ++++++++ scala3/newcomers/java.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 scala3/newcomers/java.md diff --git a/index.md b/index.md index 13b277c86d..fdf93de278 100644 --- a/index.md +++ b/index.md @@ -25,6 +25,10 @@ sections: description: "Learn Scala by reading a series of short lessons." icon: "fa fa-book-open" link: /scala3/book/introduction.html + - title: "Scala for Java Programmers" + description: "An effective approach to learning Scala as a programmer with the Java background." + icon: "fa fa-coffee" + link: /scala3/newcomers/java.html - title: Online Courses description: "MOOCs to learn Scala, for beginners and experienced programmers." icon: "fa fa-cloud" @@ -98,6 +102,10 @@ sections: description: "The Complete Guide to Contributing to Scala's compilers, libraries and documentation." icon: "fa fa-cogs" link: /contribute/ + - title: "Becoming a Scala OSS Contributor" + description: "How to start contributing to open-source Scala ecosystem" + icon: "fa fa-code-branch" + link: /scala3/newcomers/contributor.html - title: "Scala 3 Contributing Guide" description: "Guide to the Scala 3 Compiler and fixing an issue" icon: "fa fa-cogs" diff --git a/scala3/newcomers/java.md b/scala3/newcomers/java.md new file mode 100644 index 0000000000..b93c80aa16 --- /dev/null +++ b/scala3/newcomers/java.md @@ -0,0 +1,31 @@ +--- +layout: singlepage-overview +title: Scala for Java Programmers +--- +There's a saying that Scala is Java without semicolons. + +There is a truth to this statement. Scala builds upon the foundations of Java, and can use any Java library out of the box; once the project is configured, most Java programs will still work in Scala by only converting the syntax. + +Scala stands for Scalable Language – and a scalable language is supposed to scale not only with hardware resources and load requirements, but also with the level of programmer's skill. True to the spirit of a scalable language, if you choose, Scala can be much deeper than Java without semicolons. It provides you with a wide array of expressive features that, when mastered, can tremendously increase your ability as a developer, giving access to techniques that are different from those used in Java. Learning these extras are optional steps to approach at your own pace. The most fun and effective way to learn, in our opinion, is to ensure you are productive first with what knowledge you have from Java. And then, learn one thing at a time following the [Scala Book](https://docs.scala-lang.org/scala3/book/introduction.html). Pick the learning pace convenient for you and ensure whatever you are learning is fun. + +TL;DR: start writing Scala as Java without semicolons, explore from there as you see fit. + +## How to Get Started +### The Basics +First, you need somewhere to practice your code-writing. We recommend the following resources to get your playground going: + +- [Scastie](https://scastie.scala-lang.org/) the online Scala playground. Start writing Scala in a single click. +- [Install Scala](https://www.scala-lang.org/download/) on your machine. May need some work, but this is a comprehensive solution with which you can write serious projects. + +Next, you need to know what to write. The [Official Scala 3 Overview for Java Developers](https://docs.scala-lang.org/scala3/book/scala-for-java-devs.html) is a good place to start getting familiar with Scala. The document outlines how Scala differs from Java. If you feel comfortable with it, it may be a good idea to try out the snippets from the document in your playground. + +### Getting Productive +After going through the basics, you should get a good feel of how to write Scala as Java without semicolons. Next step is, how do you actually do stuff with Scala. You can't do stuff without libraries. As a Java programmer, you already know a lot of libraries that do the job in Java, so let's start with those. + +In Java, you can fetch dependencies into your project via Maven. While it is possible to [set up a Maven project with Scala](https://docs.scala-lang.org/tutorials/scala-with-maven.html), it is not a widely used way in the Scala ecosystem. The build tool of choice in Scala is [sbt](https://www.scala-sbt.org/). We recommend you to spend some time to familiarise yourself with sbt documentation, but for the impatient ones, there is always a template project option. An sbt template is an sbt project that you can fetch from the Internet with a single command so that you have something to get started with. We recommend the following template for Scala 3: [https://github.com/scala/scala3.g8](https://github.com/scala/scala3.g8). After installing sbt on your machine, you should be able to follow the readme of that template to get started. + +An SBT project is specified in the build.scala file in the root of the cloned template, and the library dependencies are specified via the libraryDependencies value in that file (also present in the example template). To learn the ropes around how to declare dependencies, see the [documentation of sbt](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#The++key). + +Caveat: you may notice that the Scala dependencies have their group name and artifact name separated with `%%`. For Java dependencies, use `%`, a single percent sign. Why? Technical detail: Scala artifact names are suffixed with Scala's binary version, e.g. munit_3 instead of munit, and the role of the `%%` is to help sbt to fill in the right suffix automatically . Since Java artifacts don't have such a naming convention, use `%`. For more information, see the [sbt documentation](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with). + +That's it! Now you can use your Java libraries from Scala! You can continue your Scala journey by reading the [Scala Book](https://docs.scala-lang.org/scala3/book/introduction.html) or following a number of [online MOOCs](https://docs.scala-lang.org/online-courses.html). From 59866e3a2eb0858fcd5e0be5a5d3f95bcc0fce75 Mon Sep 17 00:00:00 2001 From: Anatolii Kmetiuk Date: Wed, 1 Jun 2022 12:19:20 +0200 Subject: [PATCH 2/8] Add Becoming a Scala OSS Contributor article --- scala3/newcomers/contributor.md | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 scala3/newcomers/contributor.md diff --git a/scala3/newcomers/contributor.md b/scala3/newcomers/contributor.md new file mode 100644 index 0000000000..0052e67b55 --- /dev/null +++ b/scala3/newcomers/contributor.md @@ -0,0 +1,36 @@ +--- +layout: singlepage-overview +title: Becoming a Scala OSS Contributor +--- +You are a confident Scala programmer who is looking to give back to the community. Or maybe you are only at the start of your Scala journey and are looking for good ways to improve your expertise. Regardless of your background, contributing to open source Scala libraries has its own benefits for you. + +## Why contribute? +Open Source Software (OSS) libraries are the flesh on top of the bone structure of the core language itself. They power vast majority of the commercial and non-commercial projects out there alike. + +Contributing is a great way to strengthen your CV. It's also good from the community standpoint: if you do it consistently, with time, you get to know people, and people get to know you. Such a networking can lead to all sorts of opportunities. + +Contributing to open source libraries is a great way to learn Scala. A standard practice in open source software is code review – which means you are going to get expert feedback about your code. Learning together with feedback from competent people is much faster than making all the mistakes and figuring them out alone. + +Finally, by contributing you improve the projects you are using yourself. Being a part of a maintainer team can be a source of personal satisfaction, and working on an innovative library can be a lot of fun. + +The above benefits are something good to achieve regardless of your level of experience. + +## Ways to contribute +Often, when people are talking about contributing to OSS, they think of fixing issues or implementing new features. While a valuable help, these are far from the only ways you can contribute. Following are some other ways you should consider: + +- **Documentation**. Often it is outdated, incomplete, erroneous. If you see a way to improve a documentation for a project you are using, you should consider finding out if the the documentation is hosted on github in which case you can submit a pull request to fix it. +- **Issue minimization**. Many of the reported issues found on a project's issue tracker are hard to reproduce and the reproduction involves a lot of code. However, it is very frequently the case that only a tiny fraction of the reported setup and code is necessary to reproduce the issue. More reproduction code means more work for the maintainer to fix an issue. You can help them considerably by investigating already reported issues in an attempt to make their reproduction as small as possible. +- **Issue reproduction**. Some reported issues lack reproduction instructions at all! If a maintainer can't reproduce it, they won't be able to fix it. Pinning down exact conditions that make an issue manifest is another way to contribute. +- **Open-source your own project**. Do you have a pet project you are working on? Is there anything you're working on at work parts of which are generic enough that you can share them online? Open-sourcing your work is a way to solve a problem for other programmers who may also have it. If you are interested in going open-source, here is an excellent guide on how to get started: [https://docs.scala-lang.org/overviews/contributors/index.html](https://docs.scala-lang.org/overviews/contributors/index.html). + +## What should I contribute to? +The best project to contribute to is the one that you are using yourself. Take an inventory of your work and hobby projects: what OSS libraries do they use? Have you ever encountered bugs in them? Or have you ever wanted a certain feature implemented? Pick a bug and a feature and commit to fixing or implementing it. Clone the project you are trying to improve, figure out how the tests are written and run there. Write a test for your feature or bug. + +While implementing or fixing the feature, it is important to ask for help early when you feel stuck. Even if your code doesn't work, don't hesitate to submit a pull request while stating clearly that you need help. More information about the guidelines of good contribution you can find in the [talk by Seth Tisue](https://youtu.be/DTUpSTrnI-0) on how to be a good contributor. + +If you can't immediately see a bug or feature that you personally would like to use, a good idea is to learn a new Scala library, push it to its limits and see where it can be improved. You can find popular Scala libraries on [Scaladex](https://index.scala-lang.org/awesome). It's not a good idea to just pick a random library from the list and try fixing random bugs in it: you need to really spend the time with it to start seeing what's important and how to improve it right. So if you are passionate about contributing but don't see any immediate contribution options that would attract you, this should be your cue that it is time to expand your horizons and learn something new. + +There is also an option to contribute to the Scala 3 compiler itself. The Scala Center runs the Compiler Academy project to onboard and educate new people in the Scala 3 compiler. One of the Compiler Academy projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues in pair programming sessions while learning the compiler together. You can apply for the Spree participation by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). + +You may want to keep an eye on the Scala Center [LinkedIn](https://www.linkedin.com/company/scala-center/) and [Twitter](https://twitter.com/scala_lang) to stay up-to-date with the possible contribution opportunities. For example, every year, the Scala Center participates in the Google Summer of Code program where you are paid to work on open source Scala projects over the course of summer. + From 458507e296a11416556be9b7cfc28383f314a29d Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Fri, 12 Aug 2022 16:57:06 +0200 Subject: [PATCH 3/8] move Java Link from index to getting-started update fontawesome --- _getting-started/index.md | 22 +++++++++++++-------- _includes/documentation-sections.html | 2 +- _includes/headertop.html | 2 +- _includes/inner-documentation-sections.html | 20 +++++++++++++++++++ _sass/base/helper.scss | 3 ++- _sass/layout/inner-main.scss | 7 ------- _sass/layout/table-of-content.scss | 9 +++++---- index.md | 4 ---- 8 files changed, 43 insertions(+), 26 deletions(-) create mode 100644 _includes/inner-documentation-sections.html diff --git a/_getting-started/index.md b/_getting-started/index.md index 774ef9ce36..71c7a61476 100644 --- a/_getting-started/index.md +++ b/_getting-started/index.md @@ -5,6 +5,19 @@ partof: getting-started languages: [fr, ja, uk] includeTOC: true +newcomer_resources: + - title: "Resources For Newcomers" + links: + - title: Are You Coming From Java? + description: What you should know to get to speed with Scala after your initial setup. + icon: "fa fa-coffee" + link: /scala3/newcomers/java.html + - title: Scala in the Browser + description: > + To start experimenting with Scala right away, use "Scastie" in your browser. + icon: "fa fa-cloud" + link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw + redirect_from: - /getting-started.html - /scala3/getting-started.html # we deleted the scala 3 version of this page @@ -19,14 +32,7 @@ The instructions below cover both Scala 2 and Scala 3. {% endaltDetails %} -## Try Scala without installing anything - -To start experimenting with Scala right away, use “Scastie” in your browser. -_Scastie_ is an online “playground” where you can experiment with Scala examples to see how things work, with access to all Scala compilers and published libraries. - -> Scastie supports both Scala 2 and Scala 3, but it defaults -> to Scala 3. If you are looking for a Scala 2 snippet to play with, -> [click here](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA). +{% include inner-documentation-sections.html sections=page.newcomer_resources %} ## Install Scala on your computer diff --git a/_includes/documentation-sections.html b/_includes/documentation-sections.html index fd6714fc8b..cac3c2d21b 100644 --- a/_includes/documentation-sections.html +++ b/_includes/documentation-sections.html @@ -3,7 +3,7 @@

{{ section.title }}

{% for link in section.links %} - +
{{link.title}}
diff --git a/_includes/headertop.html b/_includes/headertop.html index fbb452e182..aa8efa7835 100644 --- a/_includes/headertop.html +++ b/_includes/headertop.html @@ -46,7 +46,7 @@ - + diff --git a/_includes/inner-documentation-sections.html b/_includes/inner-documentation-sections.html new file mode 100644 index 0000000000..0c2980bf14 --- /dev/null +++ b/_includes/inner-documentation-sections.html @@ -0,0 +1,20 @@ +{% comment %} + Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...) +{% endcomment %} + +{% for section in include.sections %} +

{{ section.title }}

+
+ {% for link in section.links %} + +
+ +

{{link.title}}

+
+
+

{{link.description}}

+
+ + {% endfor %} +
+{% endfor %} diff --git a/_sass/base/helper.scss b/_sass/base/helper.scss index 80297c4637..5a53ee033a 100755 --- a/_sass/base/helper.scss +++ b/_sass/base/helper.scss @@ -16,10 +16,11 @@ .inline-sticky-top { position: sticky; top: 15px; + margin-bottom: 25px; background: #fff; -webkit-box-shadow: 0 0 18px 20px #fff; -moz-box-shadow: 0 0 18px 20px #fff; - box-shadow: 0 0 18px 20px #fff; + box-shadow: 0 7px 15px 5px #fff; z-index: 5; } diff --git a/_sass/layout/inner-main.scss b/_sass/layout/inner-main.scss index 72a996231f..c76aff27b9 100755 --- a/_sass/layout/inner-main.scss +++ b/_sass/layout/inner-main.scss @@ -77,13 +77,6 @@ &:nth-child(2n) { clear: none; } - - &:active, - &:focus, - &:hover { - text-decoration: none; - background: none; - } } } } diff --git a/_sass/layout/table-of-content.scss b/_sass/layout/table-of-content.scss index 642244d0c1..28cfc05ba1 100755 --- a/_sass/layout/table-of-content.scss +++ b/_sass/layout/table-of-content.scss @@ -65,7 +65,8 @@ @include justify-content(flex-start); margin-bottom: 10px; - .fa { + .fa, + .fa-brands { font-size: 1.563rem; margin-right: 14px; color: $brand-primary; @@ -92,9 +93,9 @@ } } - &:active, - &:focus, - &:hover { + &.doc-item-link:active, + &.doc-item-link:focus, + &.doc-item-link:hover { text-decoration: none; background: $gray-lighter; } diff --git a/index.md b/index.md index fdf93de278..436c6760fa 100644 --- a/index.md +++ b/index.md @@ -25,10 +25,6 @@ sections: description: "Learn Scala by reading a series of short lessons." icon: "fa fa-book-open" link: /scala3/book/introduction.html - - title: "Scala for Java Programmers" - description: "An effective approach to learning Scala as a programmer with the Java background." - icon: "fa fa-coffee" - link: /scala3/newcomers/java.html - title: Online Courses description: "MOOCs to learn Scala, for beginners and experienced programmers." icon: "fa fa-cloud" From 1d10e89f19ae773fa16888c17be690329f553a2d Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Tue, 16 Aug 2022 10:23:59 +0200 Subject: [PATCH 4/8] move newcomer contribution to contribution guide Co-authored-by: Jamie Thompson Co-authored-by: Anatolii Kmetiuk --- _getting-started/index.md | 24 +++++++++---------- _includes/inner-documentation-sections.html | 22 ++++++++--------- _overviews/contribute/add-guides.md | 2 +- .../contribute/become-contributor.md | 8 +++---- _overviews/contribute/bug-reporting-guide.md | 2 +- _overviews/contribute/codereviews.md | 2 +- _overviews/contribute/corelibs.md | 2 +- _overviews/contribute/documentation.md | 2 +- _overviews/contribute/guide.md | 2 +- _overviews/contribute/hacker-guide.md | 2 +- .../contribute/inclusive-language-guide.md | 2 +- _overviews/contribute/index.md | 24 ++++++++++++++++++- _overviews/contribute/partest-guide.md | 2 +- _overviews/contribute/scala-internals.md | 2 +- ...cala-standard-library-api-documentation.md | 2 +- _overviews/contribute/tools.md | 2 +- index.md | 10 +++----- 17 files changed, 63 insertions(+), 49 deletions(-) rename scala3/newcomers/contributor.md => _overviews/contribute/become-contributor.md (92%) diff --git a/_getting-started/index.md b/_getting-started/index.md index 71c7a61476..dd2ea1f8de 100644 --- a/_getting-started/index.md +++ b/_getting-started/index.md @@ -6,17 +6,15 @@ languages: [fr, ja, uk] includeTOC: true newcomer_resources: - - title: "Resources For Newcomers" - links: - - title: Are You Coming From Java? - description: What you should know to get to speed with Scala after your initial setup. - icon: "fa fa-coffee" - link: /scala3/newcomers/java.html - - title: Scala in the Browser - description: > - To start experimenting with Scala right away, use "Scastie" in your browser. - icon: "fa fa-cloud" - link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw + - title: Are You Coming From Java? + description: What you should know to get to speed with Scala after your initial setup. + icon: "fa fa-coffee" + link: /scala3/newcomers/java.html + - title: Scala in the Browser + description: > + To start experimenting with Scala right away, use "Scastie" in your browser. + icon: "fa fa-cloud" + link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw redirect_from: - /getting-started.html @@ -32,7 +30,9 @@ The instructions below cover both Scala 2 and Scala 3. {% endaltDetails %}
-{% include inner-documentation-sections.html sections=page.newcomer_resources %} +## Resources For Newcomers + +{% include inner-documentation-sections.html links=page.newcomer_resources %} ## Install Scala on your computer diff --git a/_includes/inner-documentation-sections.html b/_includes/inner-documentation-sections.html index 0c2980bf14..6d9141e63c 100644 --- a/_includes/inner-documentation-sections.html +++ b/_includes/inner-documentation-sections.html @@ -2,19 +2,17 @@ Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...) {% endcomment %} -{% for section in include.sections %} -

{{ section.title }}

- {% for link in section.links %} - -
- -

{{link.title}}

-
-
-

{{link.description}}

-
+ {% for link in include.links %} + +
+ +

{{link.title}}

+
+
+

{{link.description}}

+
{% endfor %}
-{% endfor %} diff --git a/_overviews/contribute/add-guides.md b/_overviews/contribute/add-guides.md index f52764736e..5c2d2f96bd 100644 --- a/_overviews/contribute/add-guides.md +++ b/_overviews/contribute/add-guides.md @@ -1,6 +1,6 @@ --- title: Add New Guides/Tutorials -num: 7 +num: 8 --- ## Why Contribute New Learning Material? diff --git a/scala3/newcomers/contributor.md b/_overviews/contribute/become-contributor.md similarity index 92% rename from scala3/newcomers/contributor.md rename to _overviews/contribute/become-contributor.md index 0052e67b55..d4121b1fcc 100644 --- a/scala3/newcomers/contributor.md +++ b/_overviews/contribute/become-contributor.md @@ -1,8 +1,7 @@ --- -layout: singlepage-overview -title: Becoming a Scala OSS Contributor +title: Contribution FAQ +num: 2 --- -You are a confident Scala programmer who is looking to give back to the community. Or maybe you are only at the start of your Scala journey and are looking for good ways to improve your expertise. Regardless of your background, contributing to open source Scala libraries has its own benefits for you. ## Why contribute? Open Source Software (OSS) libraries are the flesh on top of the bone structure of the core language itself. They power vast majority of the commercial and non-commercial projects out there alike. @@ -23,7 +22,7 @@ Often, when people are talking about contributing to OSS, they think of fixing i - **Issue reproduction**. Some reported issues lack reproduction instructions at all! If a maintainer can't reproduce it, they won't be able to fix it. Pinning down exact conditions that make an issue manifest is another way to contribute. - **Open-source your own project**. Do you have a pet project you are working on? Is there anything you're working on at work parts of which are generic enough that you can share them online? Open-sourcing your work is a way to solve a problem for other programmers who may also have it. If you are interested in going open-source, here is an excellent guide on how to get started: [https://docs.scala-lang.org/overviews/contributors/index.html](https://docs.scala-lang.org/overviews/contributors/index.html). -## What should I contribute to? +## Choosing Where to Contribute The best project to contribute to is the one that you are using yourself. Take an inventory of your work and hobby projects: what OSS libraries do they use? Have you ever encountered bugs in them? Or have you ever wanted a certain feature implemented? Pick a bug and a feature and commit to fixing or implementing it. Clone the project you are trying to improve, figure out how the tests are written and run there. Write a test for your feature or bug. While implementing or fixing the feature, it is important to ask for help early when you feel stuck. Even if your code doesn't work, don't hesitate to submit a pull request while stating clearly that you need help. More information about the guidelines of good contribution you can find in the [talk by Seth Tisue](https://youtu.be/DTUpSTrnI-0) on how to be a good contributor. @@ -33,4 +32,3 @@ If you can't immediately see a bug or feature that you personally would like to There is also an option to contribute to the Scala 3 compiler itself. The Scala Center runs the Compiler Academy project to onboard and educate new people in the Scala 3 compiler. One of the Compiler Academy projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues in pair programming sessions while learning the compiler together. You can apply for the Spree participation by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). You may want to keep an eye on the Scala Center [LinkedIn](https://www.linkedin.com/company/scala-center/) and [Twitter](https://twitter.com/scala_lang) to stay up-to-date with the possible contribution opportunities. For example, every year, the Scala Center participates in the Google Summer of Code program where you are paid to work on open source Scala projects over the course of summer. - diff --git a/_overviews/contribute/bug-reporting-guide.md b/_overviews/contribute/bug-reporting-guide.md index 41f349016e..c159fb9899 100644 --- a/_overviews/contribute/bug-reporting-guide.md +++ b/_overviews/contribute/bug-reporting-guide.md @@ -1,6 +1,6 @@ --- title: Bug Reporting Guide -num: 8 +num: 9 --- The Scala compiler and standard library bug tracker is located at [https://github.com/scala/bug](https://github.com/scala/bug), and for Scala 3, it is located at [github.com/lampepfl/dotty](https://github.com/lampepfl/dotty/issues). Before you submit a bug make sure that it is certainly a bug by following instructions diff --git a/_overviews/contribute/codereviews.md b/_overviews/contribute/codereviews.md index c4c44c9981..406d2477d7 100644 --- a/_overviews/contribute/codereviews.md +++ b/_overviews/contribute/codereviews.md @@ -1,6 +1,6 @@ --- title: Code Review Contributions -num: 3 +num: 4 --- ## Code Review Contributions diff --git a/_overviews/contribute/corelibs.md b/_overviews/contribute/corelibs.md index 4fcab907a2..98436c770a 100644 --- a/_overviews/contribute/corelibs.md +++ b/_overviews/contribute/corelibs.md @@ -1,6 +1,6 @@ --- title: Core Library Contributions -num: 4 +num: 5 --- ## Core Library Contributions diff --git a/_overviews/contribute/documentation.md b/_overviews/contribute/documentation.md index 469396e40c..39a1f6cc18 100644 --- a/_overviews/contribute/documentation.md +++ b/_overviews/contribute/documentation.md @@ -1,6 +1,6 @@ --- title: Documentation Contributions -num: 5 +num: 6 --- ## Contributing Documentation to the Scala project diff --git a/_overviews/contribute/guide.md b/_overviews/contribute/guide.md index 9fa69a410c..c7a344d367 100644 --- a/_overviews/contribute/guide.md +++ b/_overviews/contribute/guide.md @@ -1,6 +1,6 @@ --- title: Contributing guide -num: 10 +num: 11 --- | **Shortcut** | **Description** | diff --git a/_overviews/contribute/hacker-guide.md b/_overviews/contribute/hacker-guide.md index e78df88b12..6c18577018 100644 --- a/_overviews/contribute/hacker-guide.md +++ b/_overviews/contribute/hacker-guide.md @@ -1,7 +1,7 @@ --- title: Scala 2 Hacker's Guide by: Eugene Burmako -num: 12 +num: 13 ---
This guide is intended to help you get from an idea of fixing a bug or implementing a new feature into a nightly Scala build, and, ultimately, to a production release of Scala incorporating your idea. diff --git a/_overviews/contribute/inclusive-language-guide.md b/_overviews/contribute/inclusive-language-guide.md index d32b5144a8..d88f2c51af 100644 --- a/_overviews/contribute/inclusive-language-guide.md +++ b/_overviews/contribute/inclusive-language-guide.md @@ -1,6 +1,6 @@ --- title: Inclusive Language Guide -num: 2 +num: 3 --- We are committed to providing a friendly, safe and welcoming environment for diff --git a/_overviews/contribute/index.md b/_overviews/contribute/index.md index 9e0d6e9073..5484a3b150 100644 --- a/_overviews/contribute/index.md +++ b/_overviews/contribute/index.md @@ -1,8 +1,30 @@ --- -title: Introduction +title: Becoming a Scala OSS Contributor num: 1 + +explore_resources: + - title: Why Contribute? + description: "Giving back to the community has many benefits..." + icon: "fa fa-circle-question" + link: "become-contributor.html#why-contribute" + - title: Ways to Contribute + description: "From documentation to coding a bug-fix, there is lots to do..." + icon: "fa fa-clipboard-list" + link: "become-contributor.html#ways-to-contribute" + - title: Choosing Where to Contribute + description: "If you are using OSS, you are already a contributor..." + icon: "fa fa-check-to-slot" + link: "become-contributor.html#choosing-where-to-contribute" --- +Regardless of your background, contributing to open source Scala libraries has its own benefits for you. +You could be a confident Scala programmer who is looking to give back to the community. Or maybe you are only at the +start of your Scala journey and are looking for good ways to improve your expertise. + +### Explore Scala OSS + +{% include inner-documentation-sections.html links=page.explore_resources %} + ### Why You Should Contribute To Scala The Scala programming language is an open source project with a very diverse community, where people from all over the world contribute their work, diff --git a/_overviews/contribute/partest-guide.md b/_overviews/contribute/partest-guide.md index c8eb5cbf02..c13f78dac2 100644 --- a/_overviews/contribute/partest-guide.md +++ b/_overviews/contribute/partest-guide.md @@ -1,6 +1,6 @@ --- title: Running the Test Suite -num: 13 +num: 14 --- Partest is a custom parallel testing tool that we use to run the test suite for the Scala compiler and library. Go to the scala project folder from your local checkout and run it via `sbt`, `ant` or standalone as follows. diff --git a/_overviews/contribute/scala-internals.md b/_overviews/contribute/scala-internals.md index 738746f9d3..263e5b0f9a 100644 --- a/_overviews/contribute/scala-internals.md +++ b/_overviews/contribute/scala-internals.md @@ -1,6 +1,6 @@ --- title: Scala Contributors Forum -num: 9 +num: 10 --- The [Scala Contributors Forum][scala-contributors] is where discussions about the Scala ecosystem diff --git a/_overviews/contribute/scala-standard-library-api-documentation.md b/_overviews/contribute/scala-standard-library-api-documentation.md index 692cf00a76..9919782a7f 100644 --- a/_overviews/contribute/scala-standard-library-api-documentation.md +++ b/_overviews/contribute/scala-standard-library-api-documentation.md @@ -1,6 +1,6 @@ --- title: Contribute to API Documentation -num: 6 +num: 7 --- This page is specific to API documentation contributions – that is, API diff --git a/_overviews/contribute/tools.md b/_overviews/contribute/tools.md index 77115d03ab..bd4846be88 100644 --- a/_overviews/contribute/tools.md +++ b/_overviews/contribute/tools.md @@ -1,6 +1,6 @@ --- title: IDE and Build Tool Contributions -num: 11 +num: 12 # Projects list: projects: diff --git a/index.md b/index.md index 436c6760fa..dbf2fa0056 100644 --- a/index.md +++ b/index.md @@ -94,14 +94,10 @@ sections: description: "The Scala Improvement Process. Language & compiler evolution." icon: "fa fa-cogs" link: /sips/index.html - - title: "Contributing to Scala" - description: "The Complete Guide to Contributing to Scala's compilers, libraries and documentation." - icon: "fa fa-cogs" - link: /contribute/ - - title: "Becoming a Scala OSS Contributor" - description: "How to start contributing to open-source Scala ecosystem" + - title: "Become a Scala OSS Contributor" + description: "From start to finish: discover how you can help Scala's open-source ecosystem" icon: "fa fa-code-branch" - link: /scala3/newcomers/contributor.html + link: /contribute/ - title: "Scala 3 Contributing Guide" description: "Guide to the Scala 3 Compiler and fixing an issue" icon: "fa fa-cogs" From aefdf653946c5e4687b98f3f2885755afc1b7759 Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Wed, 17 Aug 2022 17:29:52 +0200 Subject: [PATCH 5/8] add Who can Contribute FAQ --- _config.yml | 2 +- _includes/sidebar-toc-multipage-overview.html | 26 +- _overviews/contribute/become-contributor.md | 34 --- _overviews/contribute/bin-old-content.md | 68 ++++++ _overviews/contribute/index.md | 225 ++++++++++++------ index.md | 4 - 6 files changed, 232 insertions(+), 127 deletions(-) delete mode 100644 _overviews/contribute/become-contributor.md create mode 100644 _overviews/contribute/bin-old-content.md diff --git a/_config.yml b/_config.yml index fab154effe..e1aaf3c1de 100644 --- a/_config.yml +++ b/_config.yml @@ -148,7 +148,7 @@ defaults: path: "_overviews/contribute" values: partof: scala-contribution - overview-name: Contributing to Scala + overview-name: Contributing to Scala's OSS Ecosystem layout: multipage-overview permalink: "/contribute/:title.html" - diff --git a/_includes/sidebar-toc-multipage-overview.html b/_includes/sidebar-toc-multipage-overview.html index e82f7bc8d5..83890101ac 100644 --- a/_includes/sidebar-toc-multipage-overview.html +++ b/_includes/sidebar-toc-multipage-overview.html @@ -1,7 +1,7 @@ {% assign pagetype = page.type %}
-
Contents
+
Contents
{% if pagetype %} -
-
Problem with this page?
     Please help us fix it!
-
+
+
+
Problem with this page?
     Please help us fix it!
+
diff --git a/_overviews/contribute/become-contributor.md b/_overviews/contribute/become-contributor.md deleted file mode 100644 index d4121b1fcc..0000000000 --- a/_overviews/contribute/become-contributor.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Contribution FAQ -num: 2 ---- - -## Why contribute? -Open Source Software (OSS) libraries are the flesh on top of the bone structure of the core language itself. They power vast majority of the commercial and non-commercial projects out there alike. - -Contributing is a great way to strengthen your CV. It's also good from the community standpoint: if you do it consistently, with time, you get to know people, and people get to know you. Such a networking can lead to all sorts of opportunities. - -Contributing to open source libraries is a great way to learn Scala. A standard practice in open source software is code review – which means you are going to get expert feedback about your code. Learning together with feedback from competent people is much faster than making all the mistakes and figuring them out alone. - -Finally, by contributing you improve the projects you are using yourself. Being a part of a maintainer team can be a source of personal satisfaction, and working on an innovative library can be a lot of fun. - -The above benefits are something good to achieve regardless of your level of experience. - -## Ways to contribute -Often, when people are talking about contributing to OSS, they think of fixing issues or implementing new features. While a valuable help, these are far from the only ways you can contribute. Following are some other ways you should consider: - -- **Documentation**. Often it is outdated, incomplete, erroneous. If you see a way to improve a documentation for a project you are using, you should consider finding out if the the documentation is hosted on github in which case you can submit a pull request to fix it. -- **Issue minimization**. Many of the reported issues found on a project's issue tracker are hard to reproduce and the reproduction involves a lot of code. However, it is very frequently the case that only a tiny fraction of the reported setup and code is necessary to reproduce the issue. More reproduction code means more work for the maintainer to fix an issue. You can help them considerably by investigating already reported issues in an attempt to make their reproduction as small as possible. -- **Issue reproduction**. Some reported issues lack reproduction instructions at all! If a maintainer can't reproduce it, they won't be able to fix it. Pinning down exact conditions that make an issue manifest is another way to contribute. -- **Open-source your own project**. Do you have a pet project you are working on? Is there anything you're working on at work parts of which are generic enough that you can share them online? Open-sourcing your work is a way to solve a problem for other programmers who may also have it. If you are interested in going open-source, here is an excellent guide on how to get started: [https://docs.scala-lang.org/overviews/contributors/index.html](https://docs.scala-lang.org/overviews/contributors/index.html). - -## Choosing Where to Contribute -The best project to contribute to is the one that you are using yourself. Take an inventory of your work and hobby projects: what OSS libraries do they use? Have you ever encountered bugs in them? Or have you ever wanted a certain feature implemented? Pick a bug and a feature and commit to fixing or implementing it. Clone the project you are trying to improve, figure out how the tests are written and run there. Write a test for your feature or bug. - -While implementing or fixing the feature, it is important to ask for help early when you feel stuck. Even if your code doesn't work, don't hesitate to submit a pull request while stating clearly that you need help. More information about the guidelines of good contribution you can find in the [talk by Seth Tisue](https://youtu.be/DTUpSTrnI-0) on how to be a good contributor. - -If you can't immediately see a bug or feature that you personally would like to use, a good idea is to learn a new Scala library, push it to its limits and see where it can be improved. You can find popular Scala libraries on [Scaladex](https://index.scala-lang.org/awesome). It's not a good idea to just pick a random library from the list and try fixing random bugs in it: you need to really spend the time with it to start seeing what's important and how to improve it right. So if you are passionate about contributing but don't see any immediate contribution options that would attract you, this should be your cue that it is time to expand your horizons and learn something new. - -There is also an option to contribute to the Scala 3 compiler itself. The Scala Center runs the Compiler Academy project to onboard and educate new people in the Scala 3 compiler. One of the Compiler Academy projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues in pair programming sessions while learning the compiler together. You can apply for the Spree participation by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). - -You may want to keep an eye on the Scala Center [LinkedIn](https://www.linkedin.com/company/scala-center/) and [Twitter](https://twitter.com/scala_lang) to stay up-to-date with the possible contribution opportunities. For example, every year, the Scala Center participates in the Google Summer of Code program where you are paid to work on open source Scala projects over the course of summer. diff --git a/_overviews/contribute/bin-old-content.md b/_overviews/contribute/bin-old-content.md new file mode 100644 index 0000000000..1b78035118 --- /dev/null +++ b/_overviews/contribute/bin-old-content.md @@ -0,0 +1,68 @@ +--- +title: Grab Bag of Stuff +num: 15 +--- + +### Why You Should Contribute To Scala +The Scala programming language is an open source project with a very +diverse community, where people from all over the world contribute their work, +with everyone benefiting from friendly help and advice, and +kindly helping others in return. So why not join the Scala community and help +everyone make things better? + +**What Can I Do?** +That depends on what you want to contribute. Below are some getting started resources for different contribution domains. Please read all the documentation and follow all the links from the topic pages below before attempting to contribute, as many of the questions you have will already be answered. + +### Reporting bugs + +See our [bug reporting guide][bug-reporting-guide] to learn +how to efficiently report a bug. + +### Contribute + +Coordination of contribution efforts takes place on +[Scala Contributors](https://contributors.scala-lang.org/). + +{% include column-list-of-items.html collection=site.contribute_resources %} + +### Guidelines + +When contributing, please follow: + +* The [Scala Code of Conduct](https://scala-lang.org/conduct/) +* The [Inclusive Language Guide][inclusive-language-guide] + +### Community Tickets + +All issues can be found in the [Scala bug tracker](https://github.com/scala/bug), or the [Scala 3 issue tracker](https://github.com/lampepfl/dotty/issues). Most issues are labeled +to make it easier to find issues you are interested in. + +### Tools and Libraries + +The Scala ecosystem includes a great many diverse open-source projects +with their own maintainers and community of contributors. Helping out +one of these projects is another way to help Scala. Consider lending +on a hand on a project you're already using. Or, to find out about +other projects, see the +[Libraries and Tools section](https://scala-lang.org/community/#community-libraries-and-tools) +on our Community page. + +### Scala Community Build + +The Scala community build enables the Scala compiler team +to build and test a corpus of +Scala open source projects +against development versions of the Scala compiler and standard +library in order to discover regressions prior to releases. +The build uses Lightbend's +[dbuild](https://github.com/typesafehub/dbuild) tool, +which leverages [sbt](https://www.scala-sbt.org). + +If you're the maintainer -- or just an interested user! -- of an +open-source Scala library or tool, please visit the +[community build documentation](https://github.com/scala/community-build/wiki) +for guidelines on what projects are suitable for the community build +and how projects can be added. + +[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} +[inclusive-language-guide]: {% link _overviews/contribute/inclusive-language-guide.md %} diff --git a/_overviews/contribute/index.md b/_overviews/contribute/index.md index 5484a3b150..2c7160d2f7 100644 --- a/_overviews/contribute/index.md +++ b/_overviews/contribute/index.md @@ -3,88 +3,163 @@ title: Becoming a Scala OSS Contributor num: 1 explore_resources: - - title: Why Contribute? + - title: Who Can Contribute? + description: "Open source is for everyone! If you are reading this you are already a contributor..." + icon: "fa fa-hand-sparkles" + link: "#who-can-contribute-to-open-source" + - title: Why Should I Contribute? description: "Giving back to the community has many benefits..." icon: "fa fa-circle-question" - link: "become-contributor.html#why-contribute" - - title: Ways to Contribute - description: "From documentation to coding a bug-fix, there is lots to do..." + link: "#why-should-i-contribute-to-open-source" + - title: How Can I Contribute? + description: "From friendly documentation to coding a bug-fix, there is lots to do..." icon: "fa fa-clipboard-list" - link: "become-contributor.html#ways-to-contribute" - - title: Choosing Where to Contribute - description: "If you are using OSS, you are already a contributor..." + link: "#how-can-i-contribute-to-open-source" + - title: Where Should I Contribute? + description: "If you are already using OSS, or are curious about projects, you can begin right away..." icon: "fa fa-check-to-slot" - link: "become-contributor.html#choosing-where-to-contribute" + link: "#how-do-i-choose-where-to-contribute" + +contrib_resources: + - title: "Scala 3 Contributing Guide" + description: "Guide to the Scala 3 Compiler and fixing an issue" + icon: "fa fa-code-merge" + link: /scala3/guides/contribution/contribution-intro.html + - title: "Scala 2 Hackers Guide" + description: "Guide to the Scala 3 Compiler and fixing an issue" + icon: "fa fa-code-pull-request" + link: /scala3/guides/contribution/contribution-intro.html + +library_resources: + - title: Library Authors Guide + description: "Lists all the tools that library authors should setup to publish and document their libraries." + icon: "fa fa-book" + link: "/overviews/contributors/index.html" + - title: Make Projects more Inclusive + description: "How you can write code and documentation that welcomes all" + icon: "fa fa-door-open" + link: "inclusive-language-guide.html" + - title: Binary Compatability Guide + description: "Evolve your library over time, giving users the confidence to upgrade safely." + icon: "fa fa-puzzle-piece" + link: "/overviews/core/binary-compatibility-for-library-authors.html" --- -Regardless of your background, contributing to open source Scala libraries has its own benefits for you. -You could be a confident Scala programmer who is looking to give back to the community. Or maybe you are only at the -start of your Scala journey and are looking for good ways to improve your expertise. +Welcome to the guide on contributing to all parts of Scala's open-source ecosystem! -### Explore Scala OSS +## Newcomers' FAQ -{% include inner-documentation-sections.html links=page.explore_resources %} - -### Why You Should Contribute To Scala -The Scala programming language is an open source project with a very -diverse community, where people from all over the world contribute their work, -with everyone benefiting from friendly help and advice, and -kindly helping others in return. So why not join the Scala community and help -everyone make things better? - -**What Can I Do?** -That depends on what you want to contribute. Below are some getting started resources for different contribution domains. Please read all the documentation and follow all the links from the topic pages below before attempting to contribute, as many of the questions you have will already be answered. - -### Reporting bugs - -See our [bug reporting guide][bug-reporting-guide] to learn -how to efficiently report a bug. - -### Contribute - -Coordination of contribution efforts takes place on -[Scala Contributors](https://contributors.scala-lang.org/). - -{% include column-list-of-items.html collection=site.contribute_resources %} - -### Guidelines +If you are reading this page, we welcome you, regardless of your background, to begin contributing to Scala's +open-source ecosystem. Find out more by clicking the links: -When contributing, please follow: - -* The [Scala Code of Conduct](https://scala-lang.org/conduct/) -* The [Inclusive Language Guide][inclusive-language-guide] - -### Community Tickets - -All issues can be found in the [Scala bug tracker](https://github.com/scala/bug), or the [Scala 3 issue tracker](https://github.com/lampepfl/dotty/issues). Most issues are labeled -to make it easier to find issues you are interested in. - -### Tools and Libraries - -The Scala ecosystem includes a great many diverse open-source projects -with their own maintainers and community of contributors. Helping out -one of these projects is another way to help Scala. Consider lending -on a hand on a project you're already using. Or, to find out about -other projects, see the -[Libraries and Tools section](https://scala-lang.org/community/#community-libraries-and-tools) -on our Community page. - -### Scala Community Build - -The Scala community build enables the Scala compiler team -to build and test a corpus of -Scala open source projects -against development versions of the Scala compiler and standard -library in order to discover regressions prior to releases. -The build uses Lightbend's -[dbuild](https://github.com/typesafehub/dbuild) tool, -which leverages [sbt](https://www.scala-sbt.org). - -If you're the maintainer -- or just an interested user! -- of an -open-source Scala library or tool, please visit the -[community build documentation](https://github.com/scala/community-build/wiki) -for guidelines on what projects are suitable for the community build -and how projects can be added. +{% include inner-documentation-sections.html links=page.explore_resources %} -[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} -[inclusive-language-guide]: {% link _overviews/contribute/inclusive-language-guide.md %} +## Ways to Start Today + +### So You Want To Write A Library... + +Read these guides if you are a maintainer of a library, or are thinking of starting a new project: + +{% include inner-documentation-sections.html links=page.library_resources %} + +### Scala Project + +There is also an option to contribute to the Scala 3 compiler itself. The Scala Center runs the +Compiler Academy project to onboard and educate new people in the Scala 3 compiler. One of the Compiler Academy +projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues +in pair programming sessions while learning the compiler together. You can apply for the Spree participation +by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). + +{% include inner-documentation-sections.html links=page.contrib_resources %} + +## Your Questions, Answered + +{% capture backButton %} +

+ + + back + +

+{% endcapture %} + +### Who Can Contribute To Open Source? +{{backButton}} +- **Everyone:** No matter your skills or background, non-technical or otherwise, there is always + [some way](#how-can-i-contribute-to-open-source) you can contribute to a project. +- **Community organisers:** Communities often form around open source projects, perhaps you would like to help grow a + community. +- **Scala learners:** If you are at the start of your Scala journey, once you have a basic understanding of everyday + Scala programming, becoming familiar with open source code will show you new techniques, helping you to improve + your expertise. +- **Got a cool idea?** Perhaps you have gained confidence in your skills and are looking to give back to the community, + start a new project that fills that perfect niche, or maybe is the life-changing tool everyone never knew they needed. +{{backButton}} + +### Why Should I Contribute to Open Source? +{{backButton}} +- **The world is built on OSS:** + Open Source Software (OSS) libraries are the flesh on top of the bone structure of the core language itself. + They power vast majority of the commercial and non-commercial projects out there alike. +- **Become more visible:** + Contributing is a great way to strengthen your CV. It's also good from the community standpoint: if you do it + consistently, with time, you get to know people, and people get to know you. Such a networking can lead to all + sorts of opportunities. +- **Learn by doing something practical:** Contributing to open source libraries is a great way to learn Scala. + A standard practice in open source software is code review – which means you are going to get expert feedback + about your code. Learning together with feedback from competent people is much faster than making all the + mistakes and figuring them out alone. +- **Have fun and help out:** Finally, by contributing you improve the projects you are using yourself. Being a part of + a maintainer team can be a source of personal satisfaction, and working on an innovative library can be a lot of fun. + +The above benefits are something good to achieve regardless of your level of experience. +{{backButton}} + +### How Can I Contribute to Open Source? +{{backButton}} +- **Documentation:** Often it is outdated, incomplete, or with mistakes. If you see a way to improve the + documentation for a project you are using, you should consider if the project is accepting contributions, + in which case you can submit a pull request to include your changes. +- **Building community:** All projects have users, and users come together to form communities. Managing and growing + communities takes coordination and effort. +- **Issue minimization:** Many of the reported issues found on a project's issue tracker are hard to reproduce and the + reproduction involves a lot of code. However, it is very frequently the case that only a tiny fraction of the + reported setup and code is necessary to reproduce the issue. More reproduction code means more work for the + maintainer to fix an issue. You can help them considerably by investigating already reported issues in an attempt + to make their reproduction as small as possible. +- **Issue reproduction:** Some reported issues lack reproduction instructions at all! If a maintainer can't + reproduce it, they won't be able to fix it. Pinning down exact conditions that make an issue manifest is another + way to contribute. +- **Fixing a bug:** If you are comfortable with reproducing an issue, perhaps you would like to trace its + origin in code, and even try to build a solution that prevents the issue from occurring. +- **Adding a feature:** Sometimes projects maintain lists of planned or requested features, and you could assist + in bringing those ideas to reality. Although please beware - you should only do this if the core maintainers + have already approved the idea for the feature, they are not obligated to accept your additions! +- **Feel free to ask for help:** While implementing or fixing the feature, it is important to ask for help early + when you feel stuck. Even if your code doesn't work, don't hesitate to submit a pull request while stating clearly + that you need help. More information about the guidelines of good contribution you can find in the + [talk by Seth Tisue](https://youtu.be/DTUpSTrnI-0) on how to be a good contributor. +- **Open-source your own project:** Do you have a pet project you are working on? Is there anything you're working + on at work parts of which are generic enough that you can share them online? Open-sourcing your work is a way to + solve a problem for other programmers who may also have it. If you are interested in going open-source, the + [Library Author's Guide](https://docs.scala-lang.org/overviews/contributors/index.html) is an + excellent resource on how to get started. +{{backButton}} + +### How Do I Choose Where To Contribute? +{{backButton}} +- **Ask yourself, what am I using?** The best project to contribute to is the one that you are using yourself. + Take an inventory of your work and hobby projects: what OSS libraries do they use? Have you ever encountered bugs in + them? Or have you ever wanted a certain feature implemented? Pick a bug and a feature and commit to fixing or + implementing it. Clone the project you are trying to improve, figure out how the tests are written and run there. + Write a test for your feature or bug. +- **Try out an awesome library:** [Scaladex](https://index.scala-lang.org/awesome) is a great place to find new + libraries. If you are passionate about contributing but don't see any attractive opportunities to contribute + to projects you are already using, try learning a new Scala library, push it to its limits and see where it can + be improved. For best results, spend a lot of time with the library to get a feel of what's important + and what can improve. +- **Lookout for announcements:** You may want to keep an eye on the Scala Center + [LinkedIn](https://www.linkedin.com/company/scala-center/) and [Twitter](https://twitter.com/scala_lang) to stay up-to-date with the possible contribution opportunities. For example, every year, the Scala Center participates + in the Google Summer of Code program where you are paid to work on open source Scala projects over the course + of summer. +{{backButton}} diff --git a/index.md b/index.md index dbf2fa0056..c00c592de3 100644 --- a/index.md +++ b/index.md @@ -98,8 +98,4 @@ sections: description: "From start to finish: discover how you can help Scala's open-source ecosystem" icon: "fa fa-code-branch" link: /contribute/ - - title: "Scala 3 Contributing Guide" - description: "Guide to the Scala 3 Compiler and fixing an issue" - icon: "fa fa-cogs" - link: /scala3/guides/contribution/contribution-intro.html --- From 8701b170820d091c0de359001422cd7e751ecdfe Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Fri, 19 Aug 2022 16:24:02 +0200 Subject: [PATCH 6/8] include old scala intro in page --- _contribute_resources/1-documentation.md | 11 -- _contribute_resources/2-bug-fixes.md | 8 -- _contribute_resources/3-code-reviews.md | 9 -- _contribute_resources/4-core-libraries.md | 6 - .../5-ide-and-build-tools.md | 6 - _contribute_resources/6-compiler-language.md | 6 - _overviews/contribute/bin-old-content.md | 68 --------- _overviews/contribute/index.md | 135 ++++++++++++++++-- 8 files changed, 120 insertions(+), 129 deletions(-) delete mode 100644 _contribute_resources/1-documentation.md delete mode 100644 _contribute_resources/2-bug-fixes.md delete mode 100644 _contribute_resources/3-code-reviews.md delete mode 100644 _contribute_resources/4-core-libraries.md delete mode 100644 _contribute_resources/5-ide-and-build-tools.md delete mode 100644 _contribute_resources/6-compiler-language.md delete mode 100644 _overviews/contribute/bin-old-content.md diff --git a/_contribute_resources/1-documentation.md b/_contribute_resources/1-documentation.md deleted file mode 100644 index e11b539e16..0000000000 --- a/_contribute_resources/1-documentation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Documentation -link: /contribute/documentation.html -icon: fa fa-book ---- -[Library API docs][scala-standard-library-api-documentation], [new guides][add-guides] on [docs.scala-lang.org][home], and help -with [scala-lang.org](https://github.com/scala/scala-lang). - -[add-guides]: {% link _overviews/contribute/add-guides.md %} -[scala-standard-library-api-documentation]: {% link _overviews/contribute/scala-standard-library-api-documentation.md %} -[home]: {% link index.md %} diff --git a/_contribute_resources/2-bug-fixes.md b/_contribute_resources/2-bug-fixes.md deleted file mode 100644 index 7f3e5c2a78..0000000000 --- a/_contribute_resources/2-bug-fixes.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Bug fixes -link: /contribute/guide.html -icon: fa fa-bug ---- -Issues with the tools, core libraries and compiler. Also, you can help us by [reporting bugs][bug-reporting-guide]. - -[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} diff --git a/_contribute_resources/3-code-reviews.md b/_contribute_resources/3-code-reviews.md deleted file mode 100644 index e03305beb5..0000000000 --- a/_contribute_resources/3-code-reviews.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Code Reviews -link: /contribute/codereviews.html -icon: fa fa-eye ---- -Review pull requests against [scala/scala](https://github.com/scala/scala/pulls), -[lampepfl/dotty](https://github.com/lampepfl/dotty/pulls), -[scala/scala-lang](https://github.com/scala/scala-lang/pulls), -[scala/docs.scala-lang](https://github.com/scala/docs.scala-lang/pulls) and others. diff --git a/_contribute_resources/4-core-libraries.md b/_contribute_resources/4-core-libraries.md deleted file mode 100644 index 06f1018479..0000000000 --- a/_contribute_resources/4-core-libraries.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Core Libraries -link: /contribute/corelibs.html -icon: fa fa-clipboard ---- -Update and expand the capabilities of the core (and associated) Scala libraries. diff --git a/_contribute_resources/5-ide-and-build-tools.md b/_contribute_resources/5-ide-and-build-tools.md deleted file mode 100644 index 7202f0d953..0000000000 --- a/_contribute_resources/5-ide-and-build-tools.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: IDE and Build Tools -link: /contribute/tools.html -icon: fa fa-terminal ---- -Enhance the Scala tools with features for build tools, IDE plug-ins and other related projects. diff --git a/_contribute_resources/6-compiler-language.md b/_contribute_resources/6-compiler-language.md deleted file mode 100644 index d54e34fac9..0000000000 --- a/_contribute_resources/6-compiler-language.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Compiler/Language -link: /contribute/guide.html#larger-changes-new-features -icon: fa fa-cogs ---- -Larger language features and compiler enhancements including language specification and SIPs. diff --git a/_overviews/contribute/bin-old-content.md b/_overviews/contribute/bin-old-content.md deleted file mode 100644 index 1b78035118..0000000000 --- a/_overviews/contribute/bin-old-content.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Grab Bag of Stuff -num: 15 ---- - -### Why You Should Contribute To Scala -The Scala programming language is an open source project with a very -diverse community, where people from all over the world contribute their work, -with everyone benefiting from friendly help and advice, and -kindly helping others in return. So why not join the Scala community and help -everyone make things better? - -**What Can I Do?** -That depends on what you want to contribute. Below are some getting started resources for different contribution domains. Please read all the documentation and follow all the links from the topic pages below before attempting to contribute, as many of the questions you have will already be answered. - -### Reporting bugs - -See our [bug reporting guide][bug-reporting-guide] to learn -how to efficiently report a bug. - -### Contribute - -Coordination of contribution efforts takes place on -[Scala Contributors](https://contributors.scala-lang.org/). - -{% include column-list-of-items.html collection=site.contribute_resources %} - -### Guidelines - -When contributing, please follow: - -* The [Scala Code of Conduct](https://scala-lang.org/conduct/) -* The [Inclusive Language Guide][inclusive-language-guide] - -### Community Tickets - -All issues can be found in the [Scala bug tracker](https://github.com/scala/bug), or the [Scala 3 issue tracker](https://github.com/lampepfl/dotty/issues). Most issues are labeled -to make it easier to find issues you are interested in. - -### Tools and Libraries - -The Scala ecosystem includes a great many diverse open-source projects -with their own maintainers and community of contributors. Helping out -one of these projects is another way to help Scala. Consider lending -on a hand on a project you're already using. Or, to find out about -other projects, see the -[Libraries and Tools section](https://scala-lang.org/community/#community-libraries-and-tools) -on our Community page. - -### Scala Community Build - -The Scala community build enables the Scala compiler team -to build and test a corpus of -Scala open source projects -against development versions of the Scala compiler and standard -library in order to discover regressions prior to releases. -The build uses Lightbend's -[dbuild](https://github.com/typesafehub/dbuild) tool, -which leverages [sbt](https://www.scala-sbt.org). - -If you're the maintainer -- or just an interested user! -- of an -open-source Scala library or tool, please visit the -[community build documentation](https://github.com/scala/community-build/wiki) -for guidelines on what projects are suitable for the community build -and how projects can be added. - -[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} -[inclusive-language-guide]: {% link _overviews/contribute/inclusive-language-guide.md %} diff --git a/_overviews/contribute/index.md b/_overviews/contribute/index.md index 2c7160d2f7..d5843b498c 100644 --- a/_overviews/contribute/index.md +++ b/_overviews/contribute/index.md @@ -20,15 +20,42 @@ explore_resources: icon: "fa fa-check-to-slot" link: "#how-do-i-choose-where-to-contribute" -contrib_resources: +compiler_resources: - title: "Scala 3 Contributing Guide" description: "Guide to the Scala 3 Compiler and fixing an issue" icon: "fa fa-code-merge" link: /scala3/guides/contribution/contribution-intro.html - - title: "Scala 2 Hackers Guide" - description: "Guide to the Scala 3 Compiler and fixing an issue" - icon: "fa fa-code-pull-request" - link: /scala3/guides/contribution/contribution-intro.html + - title: "Compiler Academy Videos" + description: "In-depth tours of the Scala 3 compiler's internals" + icon: "fa fa-circle-play" + link: https://www.youtube.com/channel/UCIH0OgqE54-KEvYDg4LRhKQ + +scala_resources: + - title: Documentation + description: "Library API docs, new guides on docs.scala-lang.org, and help with scala-lang.org." + icon: fa fa-book + link: /contribute/documentation.html + - title: Bug fixes + description: "Issues with the tools, core libraries and compiler. Also, you can help us by reporting bugs." + icon: fa fa-bug + link: /contribute/guide.html + - title: Code Reviews + description: "Review pull requests against scala/scala, lampepfl/dotty, scala/scala-lang, scala/docs.scala-lang, + and others." + icon: fa fa-eye + link: /contribute/codereviews.html + - title: Core Libraries + description: "Update and expand the capabilities of the core (and associated) Scala libraries." + icon: fa fa-clipboard + link: /contribute/corelibs.html + - title: IDE and Build Tools + description: "Enhance the Scala tools with features for build tools, IDE plug-ins and other related projects." + icon: fa fa-terminal + link: /contribute/tools.html + - title: Compiler/Language + description: "Larger language features and compiler enhancements including language specification and SIPs." + icon: fa fa-cogs + link: /contribute/guide.html#larger-changes-new-features library_resources: - title: Library Authors Guide @@ -39,6 +66,10 @@ library_resources: description: "How you can write code and documentation that welcomes all" icon: "fa fa-door-open" link: "inclusive-language-guide.html" + - title: Create a Welcoming Community + description: "Our code of conduct is practical agreement for a healthy community" + icon: "fa fa-handshake-simple" + link: "https://scala-lang.org/conduct" - title: Binary Compatability Guide description: "Evolve your library over time, giving users the confidence to upgrade safely." icon: "fa fa-puzzle-piece" @@ -50,35 +81,104 @@ Welcome to the guide on contributing to all parts of Scala's open-source ecosyst ## Newcomers' FAQ If you are reading this page, we welcome you, regardless of your background, to begin contributing to Scala's -open-source ecosystem. Find out more by clicking the links: +open-source ecosystem. We have answered some common questions for you below: {% include inner-documentation-sections.html links=page.explore_resources %} ## Ways to Start Today +### The Scala Compiler Academy + +The [Scala Center](https://scala.epfl.ch) +runs the **Scala Compiler Academy** project to onboard and educate new people in the Scala 3 compiler. +One of the Compiler Academy +projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues +in pair programming sessions while learning the compiler together. You can apply for the Spree participation +by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). + +Before you begin, you can learn more about the Scala 3 compiler +from the following links: + +{% include inner-documentation-sections.html links=page.compiler_resources %} + ### So You Want To Write A Library... Read these guides if you are a maintainer of a library, or are thinking of starting a new project: {% include inner-documentation-sections.html links=page.library_resources %} -### Scala Project +### Want to Improve Scala Itself? +The Scala programming language is an open source project with a very +diverse community, where people from all over the world contribute their work, +with everyone benefiting from friendly help and advice, and +kindly helping others in return. -There is also an option to contribute to the Scala 3 compiler itself. The Scala Center runs the -Compiler Academy project to onboard and educate new people in the Scala 3 compiler. One of the Compiler Academy -projects is an Issue Spree – an event that takes place every 3 weeks where people fix Scala 3 compiler issues -in pair programming sessions while learning the compiler together. You can apply for the Spree participation -by [filling the form](https://forms.gle/DfoSuHFm3T6MA3L59). +Read on to learn how to join the Scala community and help +everyone make things better. + +## Contributing to the Scala Project + +**What Can I Do?** +That depends on what you want to contribute. Below are some getting started resources for different contribution domains. Please read all the documentation and follow all the links from the topic pages below before attempting to contribute, as many of the questions you have will already be answered. + +### Reporting bugs -{% include inner-documentation-sections.html links=page.contrib_resources %} +See our [bug reporting guide][bug-reporting-guide] to learn +how to efficiently report a bug. + +### Contribute + +Coordination of contribution efforts takes place on +[Scala Contributors](https://contributors.scala-lang.org/). + +{% include inner-documentation-sections.html links=page.scala_resources %} + +### Guidelines + +When contributing, please follow: + +* The [Scala Code of Conduct](https://scala-lang.org/conduct/) +* The [Inclusive Language Guide][inclusive-language-guide] + +### Community Tickets + +All issues can be found in the [Scala bug tracker](https://github.com/scala/bug), or the [Scala 3 issue tracker](https://github.com/lampepfl/dotty/issues). Most issues are labeled +to make it easier to find issues you are interested in. + +### Tools and Libraries + +The Scala ecosystem includes a great many diverse open-source projects +with their own maintainers and community of contributors. Helping out +one of these projects is another way to help Scala. Consider lending +on a hand on a project you're already using. Or, to find out about +other projects, see the +[Libraries and Tools section](https://scala-lang.org/community/#community-libraries-and-tools) +on our Community page. + +### Scala Community Build + +The Scala community build enables the Scala compiler team +to build and test a corpus of +Scala open source projects +against development versions of the Scala compiler and standard +library in order to discover regressions prior to releases. +The build uses Lightbend's +[dbuild](https://github.com/typesafehub/dbuild) tool, +which leverages [sbt](https://www.scala-sbt.org). + +If you're the maintainer -- or just an interested user! -- of an +open-source Scala library or tool, please visit the +[community build documentation](https://github.com/scala/community-build/wiki) +for guidelines on what projects are suitable for the community build +and how projects can be added. ## Your Questions, Answered {% capture backButton %}

- - back + + return to FAQ

{% endcapture %} @@ -163,3 +263,8 @@ The above benefits are something good to achieve regardless of your level of exp in the Google Summer of Code program where you are paid to work on open source Scala projects over the course of summer. {{backButton}} + + + +[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} +[inclusive-language-guide]: {% link _overviews/contribute/inclusive-language-guide.md %} From 6a8c00ff8808d237341ba394fb451349277cef52 Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Mon, 22 Aug 2022 17:07:16 +0200 Subject: [PATCH 7/8] integrate Java content in old tutorial --- _getting-started/index.md | 2 +- ...-with-scala-and-sbt-on-the-command-line.md | 8 +- .../tutorials/scala-for-java-programmers.md | 103 ++++++++++++++++-- scala3/newcomers/java.md | 31 ------ 4 files changed, 100 insertions(+), 44 deletions(-) delete mode 100644 scala3/newcomers/java.md diff --git a/_getting-started/index.md b/_getting-started/index.md index dd2ea1f8de..9b232187c1 100644 --- a/_getting-started/index.md +++ b/_getting-started/index.md @@ -9,7 +9,7 @@ newcomer_resources: - title: Are You Coming From Java? description: What you should know to get to speed with Scala after your initial setup. icon: "fa fa-coffee" - link: /scala3/newcomers/java.html + link: /tutorials/scala-for-java-programmers.html - title: Scala in the Browser description: > To start experimenting with Scala right away, use "Scastie" in your browser. diff --git a/_getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md index eec4d43631..46734762d9 100644 --- a/_getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md +++ b/_getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md @@ -93,13 +93,17 @@ libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % Here, `libraryDependencies` is a set of dependencies, and by using `+=`, we're adding the [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) dependency to the set of dependencies that sbt will go and fetch when it starts up. Now, in any Scala file, you can import classes, -objects, etc, from scala-parser-combinators with a regular import. +objects, etc, from `scala-parser-combinators` with a regular import. You can find more published libraries on [Scaladex](https://index.scala-lang.org/), the Scala library index, where you can also copy the above dependency information for pasting into your `build.sbt` file. +> **Note for Java Libraries:** For a regular Java library, you should only use one percent (`%`) between the +> organization name and artifact name. Double percent (`%%`) is a specialisation for Scala libraries. +> You can learn more about the reason for this in the [sbt documentation][sbt-docs-lib-dependencies]. + ## Next steps Continue to the next tutorial in the _getting started with sbt_ series, and learn about [testing Scala code with sbt in the command line](testing-scala-with-sbt-on-the-command-line.html). @@ -109,3 +113,5 @@ Continue to the next tutorial in the _getting started with sbt_ series, and lear - Continue learning Scala interactively online on [Scala Exercises](https://www.scala-exercises.org/scala_tutorial). - Learn about Scala's features in bite-sized pieces by stepping through our [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html). + +[sbt-docs-lib-dependencies]: https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with diff --git a/_overviews/tutorials/scala-for-java-programmers.md b/_overviews/tutorials/scala-for-java-programmers.md index 97c18492a0..7777acfc1a 100644 --- a/_overviews/tutorials/scala-for-java-programmers.md +++ b/_overviews/tutorials/scala-for-java-programmers.md @@ -6,19 +6,79 @@ partof: scala-for-java-programmers languages: [es, ko, de, it, ja, zh-tw] permalink: /tutorials/:title.html + +get_started_resources: + - title: "Getting Started" + description: "Install Scala on your computer and start writing some Scala code!" + icon: "fa fa-rocket" + link: /getting-started.html + - title: Scala in the Browser + description: > + To start experimenting with Scala right away, use "Scastie" in your browser. + icon: "fa fa-cloud" + link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw +java_resources: + - title: Scala for Java Developers + description: A cheatsheet with a comprehensive side-by-side comparison of Java and Scala. + icon: "fa fa-coffee" + link: /scala3/book/scala-for-java-devs.html +next_resources: + - title: Scala Book + description: Learn Scala by reading a series of short lessons. + icon: "fa fa-book-open" + link: /scala3/book/scala-for-java-devs.html + - title: Online Courses + description: MOOCs to learn Scala, for beginners and experienced programmers. + icon: "fa fa-cloud" + link: /scala3/book/scala-for-java-devs.html --- -By Michel Schinz and Philipp Haller +If you are coming to Scala with some Java experience already, this page should give a good overview of +the differences, and what to expect when you begin programming with Scala. For best results we suggest +to either set up a Scala toolchain on your computer, or try compiling Scala snippets in the browser with Scastie: + +{% include inner-documentation-sections.html links=page.get_started_resources %} + +## At a Glance: Why Scala? + +**Java without Semicolons:** There's a saying that Scala is Java without semicolons. +There is a lot of a truth to this statement: Scala simplifies much of the noise and boilerplate of Java, +while building upon the same foundation, sharing the same underlying types and runtime. + +**Seamless Interop:** Scala can use any Java library out of the box; including the Java standard library! +And pretty much any Java program will work the same in Scala, just by converting the syntax. + +**A Scalable Language:** the name Scala comes from Scalable Language. Scala scales not only with hardware +resources and load requirements, but also with the level of programmer's skill. If you choose, Scala +rewards you with expressive additional features, which when compared to Java, boost developer productivity and +readability of code. + +**It Grows with You:** Learning these extras are optional steps to approach at your own pace. +The most fun and effective way to learn, in our opinion, is to ensure you are productive first with what knowledge +you have from Java. And then, learn one thing at a time following the [Scala Book][scala-book]. Pick the learning pace convenient for you and ensure whatever you are learning is fun. + +**TL;DR:** You can start writing Scala as if it were Java with new syntax, then explore from there as you see fit. + +## Next Steps + +### Compare Java and Scala +The remainder of this tutorial expands upon some of the key differences between Java and Scala, +with further explanations. **If you only want a quick reference** between the two, read +*Scala for Java Developers*, it comes +with many snippets which you can try out in your chosen Scala setup: -## Introduction +{% include inner-documentation-sections.html links=page.java_resources %} -This document gives a quick introduction to the Scala language and -compiler. It is intended for people who already have some programming -experience and want an overview of what they can do with Scala. A -basic knowledge of object-oriented programming, especially in Java, is -assumed. +### Explore Further -## A First Example +When you finish these guides, we recommend to continue your Scala journey by reading the +*Scala Book* or following a number of *online MOOCs*. + +{% include inner-documentation-sections.html links=page.next_resources %} + +## Your First Program + +### Writing Hello World As a first example, we will use the standard *Hello World* program. It is not very fascinating but makes it easy to demonstrate the use of @@ -96,7 +156,11 @@ package, so can be accessed from anywhere in a program. {% endtabs %} -### Compiling the example +### Running Hello World + +> **Note:** The following assumes you are using Scala on the command line + +#### Compiling From the Command Line To compile the example, we use `scalac`, the Scala compiler. `scalac` works like most compilers: it takes a source file as argument, maybe @@ -117,7 +181,7 @@ them will be called `HelloWorld.class`, and contains a class which can be directly executed using the `scala` command, as the following section shows. -### Running the example +#### Running From the Command Line Once compiled, a Scala program can be run using the `scala` command. Its usage is very similar to the `java` command used to run Java @@ -131,7 +195,7 @@ output: Hello, World! ``` -## Interaction with Java +## Using Java Libraries One of Scala's strengths is that it makes it very easy to interact with Java code. All classes from the `java.lang` package are @@ -207,6 +271,19 @@ To conclude this section about integration with Java, it should be noted that it is also possible to inherit from Java classes and implement Java interfaces directly in Scala. +### Sidepoint: Third-Party Libraries + +Usually the standard library is not enough. As a Java programmer, you might already know a lot of Java libraries +that you'd like to use in Scala. The good news is that, as with Java, Scala's library ecosystem is built upon Maven coordinates. + +**Most Scala projects are built with sbt:** Adding third party libraries is usually managed by a build tool. +Coming from Java you may be familiar with Maven, Gradle and other such tools. +It's still possible to [use these][maven-setup] to build Scala projects, however it's common to use sbt. +See [setup a Scala Project with sbt][sbt-setup] for a guide on how +to build a project with sbt and add some dependencies. + + ## Everything is an Object Scala is a pure object-oriented language in the sense that @@ -1174,3 +1251,7 @@ presented some basic examples. The interested reader can go on, for example, by reading the *[Tour of Scala](https://docs.scala-lang.org/tour/tour-of-scala.html)*, which contains more explanations and examples, and consult the *Scala Language Specification* when needed. + +[scala-book]: {% link _overviews/scala3-book/introduction.md %} +[maven-setup]: {% link _overviews/tutorials/scala-with-maven.md %} +[sbt-setup]: {% link _getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md %}#adding-a-dependency diff --git a/scala3/newcomers/java.md b/scala3/newcomers/java.md deleted file mode 100644 index b93c80aa16..0000000000 --- a/scala3/newcomers/java.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: singlepage-overview -title: Scala for Java Programmers ---- -There's a saying that Scala is Java without semicolons. - -There is a truth to this statement. Scala builds upon the foundations of Java, and can use any Java library out of the box; once the project is configured, most Java programs will still work in Scala by only converting the syntax. - -Scala stands for Scalable Language – and a scalable language is supposed to scale not only with hardware resources and load requirements, but also with the level of programmer's skill. True to the spirit of a scalable language, if you choose, Scala can be much deeper than Java without semicolons. It provides you with a wide array of expressive features that, when mastered, can tremendously increase your ability as a developer, giving access to techniques that are different from those used in Java. Learning these extras are optional steps to approach at your own pace. The most fun and effective way to learn, in our opinion, is to ensure you are productive first with what knowledge you have from Java. And then, learn one thing at a time following the [Scala Book](https://docs.scala-lang.org/scala3/book/introduction.html). Pick the learning pace convenient for you and ensure whatever you are learning is fun. - -TL;DR: start writing Scala as Java without semicolons, explore from there as you see fit. - -## How to Get Started -### The Basics -First, you need somewhere to practice your code-writing. We recommend the following resources to get your playground going: - -- [Scastie](https://scastie.scala-lang.org/) the online Scala playground. Start writing Scala in a single click. -- [Install Scala](https://www.scala-lang.org/download/) on your machine. May need some work, but this is a comprehensive solution with which you can write serious projects. - -Next, you need to know what to write. The [Official Scala 3 Overview for Java Developers](https://docs.scala-lang.org/scala3/book/scala-for-java-devs.html) is a good place to start getting familiar with Scala. The document outlines how Scala differs from Java. If you feel comfortable with it, it may be a good idea to try out the snippets from the document in your playground. - -### Getting Productive -After going through the basics, you should get a good feel of how to write Scala as Java without semicolons. Next step is, how do you actually do stuff with Scala. You can't do stuff without libraries. As a Java programmer, you already know a lot of libraries that do the job in Java, so let's start with those. - -In Java, you can fetch dependencies into your project via Maven. While it is possible to [set up a Maven project with Scala](https://docs.scala-lang.org/tutorials/scala-with-maven.html), it is not a widely used way in the Scala ecosystem. The build tool of choice in Scala is [sbt](https://www.scala-sbt.org/). We recommend you to spend some time to familiarise yourself with sbt documentation, but for the impatient ones, there is always a template project option. An sbt template is an sbt project that you can fetch from the Internet with a single command so that you have something to get started with. We recommend the following template for Scala 3: [https://github.com/scala/scala3.g8](https://github.com/scala/scala3.g8). After installing sbt on your machine, you should be able to follow the readme of that template to get started. - -An SBT project is specified in the build.scala file in the root of the cloned template, and the library dependencies are specified via the libraryDependencies value in that file (also present in the example template). To learn the ropes around how to declare dependencies, see the [documentation of sbt](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#The++key). - -Caveat: you may notice that the Scala dependencies have their group name and artifact name separated with `%%`. For Java dependencies, use `%`, a single percent sign. Why? Technical detail: Scala artifact names are suffixed with Scala's binary version, e.g. munit_3 instead of munit, and the role of the `%%` is to help sbt to fill in the right suffix automatically . Since Java artifacts don't have such a naming convention, use `%`. For more information, see the [sbt documentation](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with). - -That's it! Now you can use your Java libraries from Scala! You can continue your Scala journey by reading the [Scala Book](https://docs.scala-lang.org/scala3/book/introduction.html) or following a number of [online MOOCs](https://docs.scala-lang.org/online-courses.html). From 520c8fefb4683e1c397dcb5490176127ad308854 Mon Sep 17 00:00:00 2001 From: Jamie Thompson Date: Mon, 22 Aug 2022 17:13:00 +0200 Subject: [PATCH 8/8] cleanups --- _config.yml | 2 -- _includes/column-list-of-items.html | 18 ------------- _includes/inner-documentation-sections.html | 26 +++++++++---------- _overviews/contribute/add-guides.md | 2 +- _overviews/contribute/bug-reporting-guide.md | 2 +- _overviews/contribute/codereviews.md | 2 +- _overviews/contribute/corelibs.md | 2 +- _overviews/contribute/documentation.md | 2 +- _overviews/contribute/guide.md | 2 +- _overviews/contribute/hacker-guide.md | 2 +- .../contribute/inclusive-language-guide.md | 2 +- _overviews/contribute/index.md | 3 --- _overviews/contribute/partest-guide.md | 2 +- _overviews/contribute/scala-internals.md | 2 +- ...cala-standard-library-api-documentation.md | 2 +- _overviews/contribute/tools.md | 2 +- 16 files changed, 25 insertions(+), 48 deletions(-) delete mode 100644 _includes/column-list-of-items.html diff --git a/_config.yml b/_config.yml index e1aaf3c1de..32dfdcdc46 100644 --- a/_config.yml +++ b/_config.yml @@ -20,8 +20,6 @@ scala-212-version: 2.12.16 scala-3-version: 3.1.3 collections: - contribute_resources: - output: false style: output: true overviews: diff --git a/_includes/column-list-of-items.html b/_includes/column-list-of-items.html deleted file mode 100644 index 2ce303e678..0000000000 --- a/_includes/column-list-of-items.html +++ /dev/null @@ -1,18 +0,0 @@ -{% comment %} - Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...) -{% endcomment %} -
- {% for item in include.collection %} -
-
- - -

{{item.title}}

- -
-
- {{item.content}} -
-
- {% endfor %} -
diff --git a/_includes/inner-documentation-sections.html b/_includes/inner-documentation-sections.html index 6d9141e63c..c26ae1c606 100644 --- a/_includes/inner-documentation-sections.html +++ b/_includes/inner-documentation-sections.html @@ -1,18 +1,18 @@ {% comment %} - Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...) + Layouts using this include should pass an include variable called 'links' referencing a list carrying the data {% endcomment %}
- {% for link in include.links %} - -
- -

{{link.title}}

-
-
-

{{link.description}}

-
- - {% endfor %} + {% for link in include.links %} + +
+ +

{{link.title}}

+
+
+

{{link.description}}

+
+ + {% endfor %}
diff --git a/_overviews/contribute/add-guides.md b/_overviews/contribute/add-guides.md index 5c2d2f96bd..f52764736e 100644 --- a/_overviews/contribute/add-guides.md +++ b/_overviews/contribute/add-guides.md @@ -1,6 +1,6 @@ --- title: Add New Guides/Tutorials -num: 8 +num: 7 --- ## Why Contribute New Learning Material? diff --git a/_overviews/contribute/bug-reporting-guide.md b/_overviews/contribute/bug-reporting-guide.md index c159fb9899..41f349016e 100644 --- a/_overviews/contribute/bug-reporting-guide.md +++ b/_overviews/contribute/bug-reporting-guide.md @@ -1,6 +1,6 @@ --- title: Bug Reporting Guide -num: 9 +num: 8 --- The Scala compiler and standard library bug tracker is located at [https://github.com/scala/bug](https://github.com/scala/bug), and for Scala 3, it is located at [github.com/lampepfl/dotty](https://github.com/lampepfl/dotty/issues). Before you submit a bug make sure that it is certainly a bug by following instructions diff --git a/_overviews/contribute/codereviews.md b/_overviews/contribute/codereviews.md index 406d2477d7..c4c44c9981 100644 --- a/_overviews/contribute/codereviews.md +++ b/_overviews/contribute/codereviews.md @@ -1,6 +1,6 @@ --- title: Code Review Contributions -num: 4 +num: 3 --- ## Code Review Contributions diff --git a/_overviews/contribute/corelibs.md b/_overviews/contribute/corelibs.md index 98436c770a..4fcab907a2 100644 --- a/_overviews/contribute/corelibs.md +++ b/_overviews/contribute/corelibs.md @@ -1,6 +1,6 @@ --- title: Core Library Contributions -num: 5 +num: 4 --- ## Core Library Contributions diff --git a/_overviews/contribute/documentation.md b/_overviews/contribute/documentation.md index 39a1f6cc18..469396e40c 100644 --- a/_overviews/contribute/documentation.md +++ b/_overviews/contribute/documentation.md @@ -1,6 +1,6 @@ --- title: Documentation Contributions -num: 6 +num: 5 --- ## Contributing Documentation to the Scala project diff --git a/_overviews/contribute/guide.md b/_overviews/contribute/guide.md index c7a344d367..9fa69a410c 100644 --- a/_overviews/contribute/guide.md +++ b/_overviews/contribute/guide.md @@ -1,6 +1,6 @@ --- title: Contributing guide -num: 11 +num: 10 --- | **Shortcut** | **Description** | diff --git a/_overviews/contribute/hacker-guide.md b/_overviews/contribute/hacker-guide.md index 6c18577018..e78df88b12 100644 --- a/_overviews/contribute/hacker-guide.md +++ b/_overviews/contribute/hacker-guide.md @@ -1,7 +1,7 @@ --- title: Scala 2 Hacker's Guide by: Eugene Burmako -num: 13 +num: 12 ---
This guide is intended to help you get from an idea of fixing a bug or implementing a new feature into a nightly Scala build, and, ultimately, to a production release of Scala incorporating your idea. diff --git a/_overviews/contribute/inclusive-language-guide.md b/_overviews/contribute/inclusive-language-guide.md index d88f2c51af..d32b5144a8 100644 --- a/_overviews/contribute/inclusive-language-guide.md +++ b/_overviews/contribute/inclusive-language-guide.md @@ -1,6 +1,6 @@ --- title: Inclusive Language Guide -num: 3 +num: 2 --- We are committed to providing a friendly, safe and welcoming environment for diff --git a/_overviews/contribute/index.md b/_overviews/contribute/index.md index d5843b498c..3187150645 100644 --- a/_overviews/contribute/index.md +++ b/_overviews/contribute/index.md @@ -194,7 +194,6 @@ and how projects can be added. your expertise. - **Got a cool idea?** Perhaps you have gained confidence in your skills and are looking to give back to the community, start a new project that fills that perfect niche, or maybe is the life-changing tool everyone never knew they needed. -{{backButton}} ### Why Should I Contribute to Open Source? {{backButton}} @@ -213,7 +212,6 @@ and how projects can be added. a maintainer team can be a source of personal satisfaction, and working on an innovative library can be a lot of fun. The above benefits are something good to achieve regardless of your level of experience. -{{backButton}} ### How Can I Contribute to Open Source? {{backButton}} @@ -244,7 +242,6 @@ The above benefits are something good to achieve regardless of your level of exp solve a problem for other programmers who may also have it. If you are interested in going open-source, the [Library Author's Guide](https://docs.scala-lang.org/overviews/contributors/index.html) is an excellent resource on how to get started. -{{backButton}} ### How Do I Choose Where To Contribute? {{backButton}} diff --git a/_overviews/contribute/partest-guide.md b/_overviews/contribute/partest-guide.md index c13f78dac2..c8eb5cbf02 100644 --- a/_overviews/contribute/partest-guide.md +++ b/_overviews/contribute/partest-guide.md @@ -1,6 +1,6 @@ --- title: Running the Test Suite -num: 14 +num: 13 --- Partest is a custom parallel testing tool that we use to run the test suite for the Scala compiler and library. Go to the scala project folder from your local checkout and run it via `sbt`, `ant` or standalone as follows. diff --git a/_overviews/contribute/scala-internals.md b/_overviews/contribute/scala-internals.md index 263e5b0f9a..738746f9d3 100644 --- a/_overviews/contribute/scala-internals.md +++ b/_overviews/contribute/scala-internals.md @@ -1,6 +1,6 @@ --- title: Scala Contributors Forum -num: 10 +num: 9 --- The [Scala Contributors Forum][scala-contributors] is where discussions about the Scala ecosystem diff --git a/_overviews/contribute/scala-standard-library-api-documentation.md b/_overviews/contribute/scala-standard-library-api-documentation.md index 9919782a7f..692cf00a76 100644 --- a/_overviews/contribute/scala-standard-library-api-documentation.md +++ b/_overviews/contribute/scala-standard-library-api-documentation.md @@ -1,6 +1,6 @@ --- title: Contribute to API Documentation -num: 7 +num: 6 --- This page is specific to API documentation contributions – that is, API diff --git a/_overviews/contribute/tools.md b/_overviews/contribute/tools.md index bd4846be88..77115d03ab 100644 --- a/_overviews/contribute/tools.md +++ b/_overviews/contribute/tools.md @@ -1,6 +1,6 @@ --- title: IDE and Build Tool Contributions -num: 12 +num: 11 # Projects list: projects: