diff --git a/README.md b/README.md index a6283b2386..fe377e9f6b 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ For more details on the Docker option, see [this issue](https://github.com/scala ## Contributing ## -Please have a look at [https://docs.scala-lang.org/contribute.html](https://docs.scala-lang.org/contribute.html) before making a contribution. +Please have a look at [Add New Guides/Tutorials](https://docs.scala-lang.org/contribute/add-guides.html) before making a contribution. This document gives an overview of the type of documentation contained within the Scala Documentation repository and the repository's structure. Small changes, or corrected typos will generally be pulled in right away. Large changes, like the addition of new documents, or the rewriting of diff --git a/_config.yml b/_config.yml index ecd8829749..43f6dfd536 100644 --- a/_config.yml +++ b/_config.yml @@ -20,6 +20,7 @@ scala-212-version: 2.12.15 scala-3-version: 3.1.1 collections: + contribute_resources: style: output: true overviews: @@ -104,6 +105,14 @@ defaults: overview-name: "Scala 3 — Book" layout: multipage-overview permalink: "/scala3/book/:title.html" + - + scope: + path: "_overviews/contribute" + values: + partof: scala-contribution + overview-name: Contributing to Scala + layout: multipage-overview + permalink: "/contribute/:title.html" - scope: path: "_overviews/scala3-migration" diff --git a/_contribute_resources/1-documentation.md b/_contribute_resources/1-documentation.md new file mode 100644 index 0000000000..e11b539e16 --- /dev/null +++ b/_contribute_resources/1-documentation.md @@ -0,0 +1,11 @@ +--- +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 new file mode 100644 index 0000000000..7026e7e15b --- /dev/null +++ b/_contribute_resources/2-bug-fixes.md @@ -0,0 +1,8 @@ +--- +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 new file mode 100644 index 0000000000..e03305beb5 --- /dev/null +++ b/_contribute_resources/3-code-reviews.md @@ -0,0 +1,9 @@ +--- +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 new file mode 100644 index 0000000000..06f1018479 --- /dev/null +++ b/_contribute_resources/4-core-libraries.md @@ -0,0 +1,6 @@ +--- +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 new file mode 100644 index 0000000000..7202f0d953 --- /dev/null +++ b/_contribute_resources/5-ide-and-build-tools.md @@ -0,0 +1,6 @@ +--- +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 new file mode 100644 index 0000000000..d54e34fac9 --- /dev/null +++ b/_contribute_resources/6-compiler-language.md @@ -0,0 +1,6 @@ +--- +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/_data/doc-nav-header.yml b/_data/doc-nav-header.yml index a96fdb3d42..52b66be1da 100644 --- a/_data/doc-nav-header.yml +++ b/_data/doc-nav-header.yml @@ -35,6 +35,8 @@ url: "/tutorials/FAQ/index.html" - title: Language Specification url: http://scala-lang.org/files/archive/spec/2.13/ + - title: Contribution Guide + url: "/contribute/" - title: Style Guide url: "/style/index.html" - title: Cheatsheet diff --git a/_data/nav-header.yml b/_data/nav-header.yml index 26bd280020..03621e6d64 100644 --- a/_data/nav-header.yml +++ b/_data/nav-header.yml @@ -1,12 +1,17 @@ - title: Documentation url: "/" + can-highlight: true - title: Download url: https://www.scala-lang.org/download/ + can-highlight: true - title: Community url: https://www.scala-lang.org/community/ + can-highlight: true - title: Libraries url: https://index.scala-lang.org + can-highlight: true - title: Contribute - url: https://www.scala-lang.org/contribute/ + url: /contribute/ - title: Blog url: https://www.scala-lang.org/blog/ + can-highlight: true diff --git a/_includes/column-list-of-items.html b/_includes/column-list-of-items.html index eb9e1600be..2ce303e678 100644 --- a/_includes/column-list-of-items.html +++ b/_includes/column-list-of-items.html @@ -15,4 +15,4 @@

{{item.title}}

{% endfor %} - \ No newline at end of file + diff --git a/_includes/site-header.html b/_includes/site-header.html index 31f2bc2a38..70f1cb6840 100644 --- a/_includes/site-header.html +++ b/_includes/site-header.html @@ -10,7 +10,7 @@ diff --git a/_ja/scala3/contribute-to-docs.md b/_ja/scala3/contribute-to-docs.md index 2902ff1d2a..c13b4b0904 100644 --- a/_ja/scala3/contribute-to-docs.md +++ b/_ja/scala3/contribute-to-docs.md @@ -45,8 +45,8 @@ Scala 3 の高品質なドキュメンテーションを作るためのいくつ - [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration) - [Issues](https://github.com/scalacenter/docs.scala-lang/issues) -## Scala 3 Contribution Guide -[Scala 3 Contribution Guide](/scala3/guides/contribution/contribution-intro.html) +## Scala 3 Contributing Guide +[Scala 3 Contributing Guide](/scala3/guides/contribution/contribution-intro.html) Scala 3 コンパイラとライブラリへの貢献と内部に関する包括的な概要が含まれています - [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) diff --git a/_ja/scala3/new-in-scala3.md b/_ja/scala3/new-in-scala3.md index eea8ee14ca..8e69859268 100644 --- a/_ja/scala3/new-in-scala3.md +++ b/_ja/scala3/new-in-scala3.md @@ -13,7 +13,7 @@ Scala 3 は Scala 2 から大幅な改善が行われ、さまざまな新機能 - [Syntax Summary][syntax-summary] では Scala 3 で新しく追加されたシンタックスを解説している。 - [Language Reference][reference] を見ればScala 2 と Scala 3 の変更点を詳しく確認できる。 - Scala 2 から Scala 3 への移行を考えている方は[Migration Guide][migration] を参照。 -- [Contribution Guide][contribution] は、問題を修正するためのガイドを含め、コンパイラーをさらに深く掘り下げます。 +- [Scala 3 Contributing Guide][contribution] は、問題を修正するためのガイドを含め、コンパイラーをさらに深く掘り下げます。 ## What's new in Scala 3 Scala 3 は Scala 2 を徹底的に見直して再設計されている。核心部分で、型システムの多くの面が変更されより原理原則に基づいたものになった。この変更によって新機能(ユニオン型)が使えるようになったことにくわえて、なにより型システムがさらに使いやすくなった。 例えば、[型推論][type-inference] や overload resolution が改善された. diff --git a/_overviews/contribute/add-guides.md b/_overviews/contribute/add-guides.md new file mode 100644 index 0000000000..bbb43a9686 --- /dev/null +++ b/_overviews/contribute/add-guides.md @@ -0,0 +1,260 @@ +--- +title: Add New Guides/Tutorials +num: 7 +--- + +## Why Contribute New Learning Material? + +As [Heather Miller writes][why-contribute], contributing to [docs.scala-lang.org][home] is +critical to making Scala accessible to newcomers, experienced programmers, and anyone who is curious. +It is also a fantastic way to contribute for anyone who is comfortable using Scala, but maybe does not want to get +involved with complex tools like the compiler. + +## Architecture + +This documentation website is backed by an open-source [github repository](https://github.com/scala/docs.scala-lang), +and is always contribution-ready. + +### Content + +Currently, the _types_ of documentation supported in this repository are: + +- **Guides/Overviews/Books**: Definitive guides/overviews of specific language features. Often long, detailed documents, + often produced by members of the Scala team. An example is the [Collections][collections-overview] overview. +- **References**: The canonical reference for language features, written by members of the Scala team. + These provide the exact specification to understand more subtle aspects of the language. An example is the + [Scala 3 reference][scala-3-reference]. +- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. +- **Cheatsheets**: Quick reference of Scala syntax and behaviors. + +### Implementation + +The website is statically generated from [Markdown](https://en.wikipedia.org/wiki/Markdown) source using +[Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](https://pages.github.com/). +This workflow was chosen to help contributors to focus on writing helpful content, rather than on configuration and +boilerplate. It also aids publishing a static site in a central location. + +The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic +syntax highlighting, without the need for any tags. + +Additionally [mdoc](https://github.com/scalameta/mdoc) is used during pull requests to validate Scala code blocks. +To use this feature you must use the backtick notation as documented by mdoc, +[see here](#code-blocks) for an example. + +**Note:** only validation of code is done by mdoc, and no extra output is generated. + +## Submitting Docs + +To contribute a new document, you should first +[fork](https://help.github.com/articles/fork-a-repo/) the +[repo](https://github.com/scala/docs.scala-lang), then write your article in +[Markdown](https://daringfireball.net/projects/markdown/syntax) (example below), and finally submit a pull request. +Likely after some edits and discussion, your document will be made live +on [docs.scala-lang.org][home]. + + --- + layout: singlepage-overview + title: My Awesome Title + --- + + ## An h2 Header in Markdown + + And a paragraph, with a [link](https://www.scala-lang.org). + +You can contribute code in a markdown document by either +- in-line by putting backticks around it, +- surrounding by triple backticks, +- or indenting it by 4 spaces, e.g.: + +~~~ +inline example: `val x = 23` + +block example: +```scala +println("hello") +``` + +indented example: + + case class Foo(x: Int) +~~~ + +Tables of contents will be automatically generated in a sidebar for your document, and syntax highlighting +is provided. + +### Criteria for Docs to be Accepted + +The goal of this documentation repository is to be highly curated, rather than the approach by other community-driven +documentation platforms, like wikis. Therefore, to be included on [docs.scala-lang.org][home], a document must: + +- **"fit in"** to the repository (_i.e.,_ it should not be a complete duplicate of another article), +- **be polished**, i.e. it must be thorough, complete, correct, and organized; written as an article to be understood + by many users. +- **be maintained**, if the document might require revisions from time to time, be prepared to keep it up to date, or +nominate someone to take ownership. + +If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute +-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the +`#scala-contributors` room [on Discord](https://discord.com/invite/scala) for any questions, concerns, +clarifications, etc. + +## Document Templates + +### Guides/Overviews + +A guide or an overview that can be logically placed on **one** markdown page should be placed in the directory +`_overviews/RELEVANT-CATEGORY/`. It should have the header: + + --- + layout: singlepage-overview + title: YOUR TITLE + --- + +The rest of the document will be written in [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax. + +You may substitute `RELEVANT-CATEGORY` for any directory that is related, or create a new one if one is not suitable. + +If your guide/overview consists of **multiple** pages, like the [Collections][collections-overview] overview, +an ordering must be specified, by numbering documents in their logical order with the `num` tag in the header, +and a name must be assigned to the collection of pages using the `partof` tag. +For example, the following header might be used for a document in the collections overview: + + --- + layout: multipage-overview + title: YOUR TITLE + + partof: collections + num: 10 + --- + +**At least one** document in the collection must contain a tag in the header, `outof`, that indicates the total number +of documents in the large overview. Putting it on the last page in the overview is often best: + + --- + layout: multipage-overview + title: YOUR TITLE + + partof: collections + num: 15 + outof: 15 + --- + +Index pages, such as [docs.scala-lang.org/overviews/index.html][overviews-index] are +generated by reading data from a configuration file, such as `_data/overviews.yml`, so your overview should be +placed into a category there. + +### Tutorials + +Tutorials are different to guides, they should be written in a much more concise, task-oriented style, +usually on a single page. + +Similar to guides, tutorials also use the same markdown header. + +Once the tutorial is written, to aid user navigation their link must be added to +the metadata of `/tutorials.md`. e.g. it could look like + + --- + layout: inner-page-parent + title: Tutorials + + tutorials: + ... + - title: My New Tutorial + url: "/tutorials/my-new-tutorial.html" + description: "Learn How To Do This Specific Task" + icon: code + --- + +You must also add the tutorial to the drop down list in the navigation bar. To do this, add an extra entry to +`_data/doc-nav-header.yml`. i.e. + + --- + - title: Getting Started + url: "/getting-started/index.html" + - title: Learn + ... + - title: Tutorials + url: "#" + submenu: + ... + - title: My New Tutorial + url: "/tutorials/my-new-tutorial.html" + ... + --- + +### Cheatsheets + +Cheatsheets have a special layout, and the content is expected to be a markdown table. To contribute a cheatsheet, +you should use the following format: + + --- + layout: cheatsheet + title: YOUR TITLE + by: YOUR NAME + about: SOME TEXT ABOUT THE CHEAT SHEET. + --- + | Title A | Title B | + |---------|---------| + | content | more | + +### Code blocks + +The site build process uses [mdoc](https://scalameta.org/mdoc/) to typecheck +code snippets in markdown. This is a great way to ensure the code snippets that +you're including typecheck and are valid. Here are a few quick tips to get +started: + +First, add `mdoc` after `scala` when you are creating a +code block. The `mdoc` modifier here will make sure that `mdoc` runs the code +snippet and ensures that it's valid. + +
+
+
+            ```scala mdoc
+val a = 1
+```
+ +If you have a snippet that you expect to fail, you can also account for this by +using `mdoc:fail` for a compile error `mdoc:crash` for a runtime-error. + +
```scala mdoc:fail
+val b: String = 3 // won't compile
+```
+ +Keep in mind that a single file is all compiled as a single unit, so you can't +redefine a variable that was defined above in another code snippet. _However_ +there are a couple ways to get around this. Firstly, you can use the `mdoc:nest` +modifier with will wrap the snippet in a `scala.Predef.locally{...}`. This will +essentially "hide" the snippet from the others. Another way around this is to +use the `mdoc:reset` modifier, which _resets_ and forgets about everything up +above. Here is an example using the various modifiers. + +
```scala mdoc
+import java.time.Instant
+
+def now() = Instant.now()
+object Foo {}
+```
+ +
```scala mdoc:nest
+case class Foo(a: Int) // conflicts with Foo above, but it's nested so it's fine
+```
+ +
```scala mdoc
+val a = s"The time is ${now()}" // still have access to the now method from above
+```
+ +
```scala mdoc:reset
+case class Foo(a: String) // forget the previous Foo's and start fresh
+```
+ +
```scala mdoc
+val myFoo = Foo("hi") // now we only have access to the last Foo
+```
+ +[collections-overview]: {% link _overviews/collections-2.13/introduction.md %} +[why-contribute]: {% link contribute.md %} +[home]: {% link index.md %} +[overviews-index]: {% link _overviews/index.md %} +[scala-3-reference]: https://docs.scala-lang.org/scala3/reference/overview.html diff --git a/_overviews/contribute/bug-reporting-guide.md b/_overviews/contribute/bug-reporting-guide.md new file mode 100644 index 0000000000..6830c18ab9 --- /dev/null +++ b/_overviews/contribute/bug-reporting-guide.md @@ -0,0 +1,90 @@ +--- +title: Bug Reporting Guide +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 +in [Is it a Bug?](#is-it-a-bug). + +## Is it a Bug? + +The first step in identifying a bug is to identify which component of the Scala distribution is affected. First, ensure that your issue falls within any of the following categories: + + - **Library** bugs typically manifest themselves as run-time exceptions, or as *unexpected*/*unintuitive* behavior of Scala Standard Library methods. + - **Compiler** errors are manifested as compile time exceptions, unexpected behavior of your code at run time, or invalid behavior of the type system. + - **Reflection** are bugs that appear in the `scala.reflect` package. For the *reflection* bugs, the same rules apply as for the *library* bugs. + - **Scaladoc** bugs are manifested as a logical problems in the information it presents (that is, the displayed information is incorrect, such as an incorrect subclassing relationship), or incorrect behavior of the user interface. If you'd like to suggest a change in the content of the documentation, please submit a pull request (possible to do in the browser using GitHub, which is easier and faster than filing a bug). Please file a bug about the content of documentation only if you cannot provide a suggestion for its fix. + +If your issue is related to any of the following external projects, make sure to use its appropriate issue tracker: + + - [Akka](https://doc.akka.io/docs/akka/current/project/issue-tracking.html) + - [Play!](https://github.com/playframework/Play20/issues) + - [Slick](https://github.com/slick/slick/issues) + - [sbt](https://github.com/sbt/sbt/issues) + +The following are generally considered to be bugs: + +- **Scala Compiler Crash** If the Scala compiler is crashing with an internal error (compile time exception) you have certainly found a bug, and can move on to the next section of this document on reporting confirmed bugs. +- **Regressions** If some code snippet worked in a previous Scala release, but now no longer compiles or results in an exception, it is probably a regression. +- **Verify Errors** happen when the compiled Scala program is loaded to the Java Virtual Machine. If you're getting a *Verify Error*, you've usually found a bug. Make sure first that your project is not using stale `.class` files before reporting a new issue. + +If you have a code snippet that is resulting in bytecode which you believe is behaving incorrectly, you may or may not have found a bug. Before reporting your issue, please attempt the following: + +* Make sure you minimize your problem. To correctly minimize the problem follow the following instructions: + + 1. Gradually remove parts from the original failing code snippet until you believe you have the simplest representation of your problem. + + 2. Ensure that you have decoupled your code snippet from any library that could be introducing the incorrect behavior. One way to achieve this is to try to recompile the offending code snippet in isolation, outside of the context of any complex build environment. If your code depends on some strictly Java library and source code is available for it, make sure that the latter is also minimized. + + 3. Make sure you are compiling your project from a clean slate. Your problem could be related to separate compilation, which is difficult to detect without a clean build with new `.class` files. + + 4. If you have encountered a bug while building your code in the IDE, then please reproduce it on the command line. The same rule applies for build tools like **sbt** or **Mill**. + + 5. If you want to file an improvement in the issue tracker please discuss it first on one of the mailing lists. They offer much bigger audience than issue tracker. The latter is not suitable for long discussions. + +* Keep in mind that the behavior you are witnessing could be intended. Good formal resources for verifying whether or not the language behavior is intended is either in the [Scala Improvement Proposal Documents][sips] or in the [Scala Language Specification](https://www.scala-lang.org/files/archive/spec/2.13/). If in doubt, you may always ask on the [Community Category](https://contributors.scala-lang.org/c/community) or [Stack Overflow](https://stackoverflow.com/questions/tagged/scala). + +In general, if you find yourself stuck on any of these steps, asking on [Scala Contributors](https://contributors.scala-lang.org/) can be helpful: + + - For unexpected behavior use the [Community Category](https://contributors.scala-lang.org/c/community). + - For compiler bugs use the [Compiler Category](https://contributors.scala-lang.org/c/compiler). + +* Examples of exceptions reported by the compiler which usually are not bugs: + 1. `StackOverflowError` is typically not a bug unless the stacktrace involves the internal packages of the compiler (like `scala.tools.nsc...`, or `dotty.tools.dotc...`). Try to increase the Java stack size (`-Xss`), in most of the cases it helps. + 2. `AbstractMethodError` can occur when you did not recompile all the necessary Scala files (build tools, like `sbt`, can prevent that from happening) or you are mixing external libraries compiled for different Scala versions (for example one uses `2.10.x` and the other `2.11.x`). + +## Please Check Before Reporting a Bug + +Before reporting your bug, make sure to check the issue tracker for other similar bugs. The exception name or a compiler phase are the best keywords to search for. If you are experiencing unexpected behavior search for method/class names where it happens. Your issue might already be reported, and a workaround might already be available for you take advantage of. If your issue *is* reported, be sure to add your test case as a comment if it is different from any of the existing ones. + +**Note:** reporting a bug that already exists creates an additional overhead for you, the Scala Team, and all people that search the issue database. To avoid this inconvenience make sure that you thoroughly search for an existing issue. + +If you cannot find your issue in the issue tracker, create a new bug. The details about creating a bug report are in the following section. + +## Creating a Bug Report + +Please make sure to fill in as many fields as possible. Make sure you've indicated the following: + + 1. **Exact Scala version** that you are using. For example, `2.13.8` or `3.1.2-RC1`. If the bug happens in multiple versions indicate all of them. + 2. **The component** that is affected by the bug. For example, the Standard Library, Scaladoc, etc. + 3. **Labels** related to your issue. For example, if you think your issue is related to the typechecker, and if you have successfully minimized your issue, label your bug as "typechecker" and "minimized". Issue tracker will suggest names for existing labels as you type them so try not to create duplicates. + 4. **Running environment**. Are you running on Linux? Windows? What JVM version are you using? + +In order for us to quickly triage the bug that you've found, it's important that the code snippet which produces the observed issue is as minimized as possible. For advice on minimizing your code snippet, please see the appropriate subsection of the above ([Is it a Bug?](#is-it-a-bug)). + +### Description + +In the description of your issue, be as detailed as you can. Bug reports which have the following information included are typically understood, triaged, and fixed very quickly: +1. Include a test case (minimized if possible) enabling us to reproduce the problematic behavior. Include your test +case (and output) in properly formatted code blocks: +~~~ +```scala +List(1, 2, 3).map(x => x + 1) +``` +~~~ +2. The expected output. +3. The actual output, including the stacktrace. +4. Related discussion on the mailing lists, if applicable. +5. If you have already looked into the issue provide interesting insights or proposals for fixing the issue. + +[sips]: {% link _sips/index.md %} diff --git a/_overviews/contribute/codereviews.md b/_overviews/contribute/codereviews.md new file mode 100644 index 0000000000..be8e66ba46 --- /dev/null +++ b/_overviews/contribute/codereviews.md @@ -0,0 +1,60 @@ +--- +title: Code Review Contributions +num: 3 +--- +## Code Review Contributions + +In addition to [bug fixing][bug-fixing], you can help us review +[waiting pull requests](#pull-requests-awaiting-comment). +This is also a good (and recommended) way to get to know the feel of +the bug-fixing and submissions process before jumping in with your +own pull requests. + + +### Review Guidelines + +[Code of Conduct reminder](https://scala-lang.org/conduct.html) + +* Keep comments on-topic, concise and precise. +* Attach comments to particular lines or regions they pertain to whenever possible. +* Short code examples are often more descriptive than prose. +* If you have thoroughly reviewed the PR and thought through all angles, LGTM (Looks Good To Me) is the preferred acceptance response. +* Additional reviews should try to offer additional insights: "I also thought about it from this angle and it still looks good.." +* Above all, remember that the people you are reviewing might be reviewing your PRs one day too. +* If you are receiving the review, consider that the advice is being given to make you, and Scala, better rather than as a negative critique. Assume the best, rather than the worst. + +## Pull Requests Awaiting Comment + +
+
+
+

lampepfl/dotty

+

Scala 3 bug fixes and changes in the language, core libs and included tools.

+
+
+

scala/scala

+

Scala 2 bug fixes and changes in the language, core libs and included tools.

+
+
+
+
+

scala/scala-lang

+

The Scala language web site.

+
+
+

scala/docs.scala-lang.org

+

Scala documentation site.

+
+
+
+
+

All Scala GitHub Projects

+

For other PRs, follow the scala project from here.

+
+
+
+ +Also note that the [Tools contributions][tools] page has more projects that will generate pull requests. + +[bug-fixing]: {% link _overviews/contribute/guide.md %} +[tools]: {% link _overviews/contribute/tools.md %} diff --git a/_overviews/contribute/corelibs.md b/_overviews/contribute/corelibs.md new file mode 100644 index 0000000000..4fcab907a2 --- /dev/null +++ b/_overviews/contribute/corelibs.md @@ -0,0 +1,21 @@ +--- +title: Core Library Contributions +num: 4 +--- +## Core Library Contributions + +There are several options for contributing to Scala's core libraries. You can: + +* Help with [Documentation][documentation]. +* [Report Bugs or Issues][bug-reporting-guide] against the core libraries. +* [Fix Bugs or Issues][guide] against the + [reported library bugs/issues](https://github.com/scala/bug). + +### Significant changes + +For significant new functionality or a whole new API to be considered for inclusion in the core Scala distribution, +please take into account [scala/scala-dev#661](https://github.com/scala/scala-dev/issues/661) before doing so. + +[documentation]: {% link _overviews/contribute/documentation.md %} +[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} +[guide]: {% link _overviews/contribute/guide.md %} diff --git a/_overviews/contribute/documentation.md b/_overviews/contribute/documentation.md new file mode 100644 index 0000000000..bd93b7fbd3 --- /dev/null +++ b/_overviews/contribute/documentation.md @@ -0,0 +1,60 @@ +--- +title: Documentation Contributions +num: 5 +--- +## Contributing Documentation to the Scala project + +There are several ways you can help out with the improvement of Scala documentation. These include: + +* API Documentation in Scaladoc +* Guides, Overviews, Tutorials, Cheat Sheets and more on the [docs.scala-lang.org][home] site +* Updating [scala-lang.org](https://scala-lang.org) + +Please read this page, and the pages linked from this one, fully before contributing documentation. Many frequently asked questions will be answered in these resources. If you have a question that isn't answered, feel free to ask on the [Scala Contributors](https://contributors.scala-lang.org/) forum and then, please, submit a pull request with updated documentation reflecting that answer. + +**General requirements** for documentation submissions include spell-checking all written language, ensuring code samples compile and run correctly, correct grammar, and clean formatting/layout of the documentation. + +Thanks + +### API Documentation (Scaladoc) + +The Scala API documentation lives with the scala project source code. There are many ways you can help with improving Scaladoc, including: + +* [Log issues for missing scaladoc documentation][report-api-doc-bugs] - +Please *follow the issue submission process closely* to help prevent duplicate issues being created. +* [Claim Scaladoc Issues and Provide Documentation][scala-standard-library-api-documentation] - please claim issues prior to working on a specific scaladoc task to prevent duplication of effort. If you sit on an issue for too long without submitting a pull request, it will revert back to unassigned and you will need to re-claim it. +* You can also just +[submit new Scaladoc][scala-standard-library-api-documentation] +without creating an issue, but please look to see if there is an issue already submitted for your task and claim it if there is. If not, please post your intention to work on a specific scaladoc task on [Scala Contributors](https://contributors.scala-lang.org/) so that people know what you are doing. + +### The Main Scala Documentation Site + +[docs.scala-lang.org][home] houses the primary source of written, non-API documentation for Scala. It's a GitHub project that you can fork and submit pull requests from. It includes: + +* Overviews +* Tutorials +* Conversion Guides from Other Languages +* Cheat Sheets +* A Glossary +* The Scala Style Guide +* The Scala Language Specification +* SIP (Scala Improvement Process) Proposals +and more + +Please read [Add New Guides/Tutorials][add-guides] through before embarking on changes. The site uses +the [Jekyll](https://jekyllrb.com/) markdown engine so you will need to follow the instructions to get that running as well. + +### Updating scala-lang.org + +Additional high-level documentation (including documentation on contributing +to Scala and related projects) is provided on the main +[Scala Language site](https://scala-lang.org), and is also kept in the +[scala-lang GitHub project](https://github.com/scala/scala-lang) which may be forked to create pull requests. + +Please read both the +[Add New Guides/Tutorials][add-guides] document and the [scala-lang.org GitHub README](https://github.com/scala/scala-lang#scala-langorg) before embarking on any changes to the Scala language site, as it uses the same Jekyll markdown tool and many of the same conventions as the Scala documentation site. + +[report-api-doc-bugs]: {% link _overviews/contribute/scala-standard-library-api-documentation.md %}#contribute-api-documentation-bug-reports +[scala-standard-library-api-documentation]: {% link _overviews/contribute/scala-standard-library-api-documentation.md %} +[home]: {% link index.md %} +[add-guides]: {% link _overviews/contribute/add-guides.md %} diff --git a/_overviews/contribute/guide.md b/_overviews/contribute/guide.md new file mode 100644 index 0000000000..33330f511d --- /dev/null +++ b/_overviews/contribute/guide.md @@ -0,0 +1,84 @@ +--- +title: Contributing guide +num: 10 +--- + +| **Shortcut** | **Description** | +|----------------------------------------|-----------------| +| [Scala Contributors][contrib-forum] | Get a peek into the inners of the Scala compiler. | +| [Report an Issue][bug-reporting-guide] | File a bug report or a feature request. | +| [Community Issues][community-tickets] | Get cracking on some easy to approach issues. | +| [Scala 2 Hacker's Guide][hackers] | Learn to write good code and improve your chances of contributing to the Scala galaxy. | +| [Scala 3 Contributing Guide][scala3-hackers] | Walkthrough contributing to the Scala 3 compiler, along with a guide to compiler internals. | + + + +### Why contribute a patch to Scala? + +Just to name a few common reasons: + +* contributing a patch is the best way to make sure your desired changes will be available in the next Scala version +* Scala is written in Scala, so going through the source code and patching it will improve your knowledge of Scala. +* last but not least, it only takes a few accepted commits to make it into the [Scala Contributor Hall of Fame](https://github.com/scala/scala/contributors). + +The main Scala project consists of the standard Scala library, the Scala reflection and macros library, +the Scala compiler and the Scaladoc tool. This means there's plenty to choose from when deciding what to work on. +Typically the scaladoc tool provides a low entry point for new committers, so it is a good first step into contributing. + +On the [Scala bug tracker](https://github.com/scala/bug) you will find the bugs that you could pick up. Once you decided on a ticket to look at, see the next step on how to proceed further. + +If you are interested in contributing code, we ask you to sign the +[Scala Contributor License Agreement](https://www.lightbend.com/contribute/cla/scala), +which allows us to ensure that all code submitted to the project is +unencumbered by copyrights or patents. + +### Bug-fix Check List +> Originally these steps cover the [Scala 2 compiler](https://github.com/scala/scala), but they also are relevant to +> the [Scala 3 compiler](https://github.com/lampepfl/dotty). + +This is the impatient developer's checklist for the steps to submit a bug-fix pull request to the Scala project. For more information, description and justification for the steps, follow the links in that step. Further specific instructions for the release of Scala you are targeting can be found in the `CONTRIBUTING.md` file for that [GitHub branch](https://github.com/scala/scala) + +1. [Select a bug to fix from GitHub][community-tickets], or if you found the bug yourself and want to fix it, [create a GitHub issue][bug-reporting-guide] (but please +[make sure it's not a duplicate][bug-report-check-dupes]). +2. Optional ([but recommended][why-its-a-good-idea]), announce your intention to work on the bug on [Scala Contributors](https://contributors.scala-lang.org/). After all, don't you want to work on a team with +[these friendly people][hackers-connect] - it's one of the perks of contributing. +3. [Fork the Scala repository][hackers-fork] and clone your fork (if you haven't already). +4. [Create a feature branch][hackers-branch] to work on: use the branch name `issue/NNNN` where NNNN is the GitHub issue number. +5. [Fix the bug, or implement the new small feature][hackers-implement], include new tests (yes, for bug fixes too). +6. [Test, rinse][hackers-test] and [test some more][partest-guide] until [all the tests pass][hackers-verify]. +7. [Commit your changes][hackers-commit] to your feature branch in your fork. Please choose your commit message based on the [Git Hygiene](https://github.com/scala/scala#user-content-git-hygiene) section of the Scala project README. +8. If necessary [re-write git history](https://git-scm.com/book/en/Git-Branching-Rebasing) so that [commits are organized by major steps to the fix/feature]( +https://github.com/scala/scala#git-hygiene). For bug fixes, a single commit is requested, for features several commits may be desirable (but each separate commit must compile and pass all tests) +9. [Submit a pull request][hackers-submit]. +10. [Work with a reviewer](https://github.com/scala/scala#reviewing) to [get your pull request merged in][hackers-review]. +11. Celebrate! + +Need more information or a little more hand-holding for the first one? We got you covered: take a read through the entire [Hacker Guide][hackers] (or the [equivalent Scala 3 Contributing Guide][scala3-hackers]) for an example of implementing a new feature (some of the steps can be skipped for bug fixes, this will be obvious from reading it, but many of the steps here will help with bug fixes too). + +### Larger Changes, New Features + +For larger, more ambitious changes (e.g. new language features), the first step to making a change is to discuss it with the community at large, to make sure everyone agrees on the idea +and on the implementation plan. Announce the change +on the [Scala Contributors](https://contributors.scala-lang.org/) mailing list and get developer feedback. For really complex changes, a [Scala Improvement Process (SIP)][sips] document might be required, but the first step is always to discuss it on the mailing list and if a SIP is required, that will be discussed on the mailing list. + +Contributions, big or small, simple or complex, controversial or undisputed, need to materialize as patches against +the Scala project source tree. The hacker's guides ([Scala 2][hackers], or [Scala 3][scala3-hackers]) will explain how to materialize your idea into a full-fledged pull request against the Scala code base. + +[hackers]: {% link _overviews/contribute/hacker-guide.md %} +[community-tickets]: {% link _overviews/contribute/index.md %}#community-tickets +[bug-reporting-guide]: {% link _overviews/contribute/bug-reporting-guide.md %} +[bug-report-check-dupes]: {% link _overviews/contribute/bug-reporting-guide.md %}#please-check-before-reporting-a-bug +[scala3-hackers]: {% link _overviews/scala3-contribution/procedures-intro.md %} +[contrib-forum]: https://contributors.scala-lang.org/ +[why-its-a-good-idea]: {% link _overviews/contribute/scala-internals.md %}#why-its-a-good-idea +[hackers-connect]: {% link _overviews/contribute/hacker-guide.md %}#1-connect +[hackers-fork]: {% link _overviews/contribute/hacker-guide.md %}#fork +[hackers-branch]: {% link _overviews/contribute/hacker-guide.md %}#branch +[hackers-implement]: {% link _overviews/contribute/hacker-guide.md %}#implement +[hackers-test]: {% link _overviews/contribute/hacker-guide.md %}#test +[hackers-verify]: {% link _overviews/contribute/hacker-guide.md %}#verify +[hackers-commit]: {% link _overviews/contribute/hacker-guide.md %}#commit +[hackers-submit]: {% link _overviews/contribute/hacker-guide.md %}#submit +[hackers-review]: {% link _overviews/contribute/hacker-guide.md %}#review +[partest-guide]: {% link _overviews/contribute/partest-guide.md %} +[sips]: {% link _sips/index.md %} diff --git a/_overviews/contribute/hacker-guide.md b/_overviews/contribute/hacker-guide.md new file mode 100644 index 0000000000..2a70714f53 --- /dev/null +++ b/_overviews/contribute/hacker-guide.md @@ -0,0 +1,387 @@ +--- +title: Scala 2 Hacker's Guide +by: Eugene Burmako +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. + +This guide covers the entire process, from the conception of your idea or bugfix to the point where it is merged into Scala. Throughout, we will use a running example of an idea or bugfix one might wish to contribute. + +Other good starting points for first-time contributors include the [Scala README](https://github.com/scala/scala#get-in-touch) and [contributor's guidelines](https://github.com/scala/scala/blob/2.13.x/CONTRIBUTING.md). + +## The Running Example + +Let's say that you particularly enjoy the new string interpolation language feature introduced in Scala 2.10.0, and you use it quite heavily. + +Though, there's an annoying issue +which you occasionally stumble upon: the formatting string interpolator `f` [does not support](https://github.com/scala/bug/issues/6725) +new line tokens `%n`. + +One approach would be to go the [Scala 2 bug tracker](https://github.com/scala/bug), request that the bug be fixed, and then to wait indefinitely for the fix arrive. Another approach would be to instead patch Scala yourself, and to submit the fix to the Scala repository in hopes that it might make it into a subsequent release. + +**_Of note_**: There are several types of releases/builds. Nightly builds are produced every night at a fixed time. Minor releases happen once every few months. Major releases typically happen once per year. + +## 1. Connect + +Sometimes it's appealing to hack alone and not to have to interact with others. However, in the context a big project such as Scala, there might be better ways. There are people in the Scala community who have spent years accumulating knowledge about Scala libraries and internals. They might provide +unique insights and, what's even better, direct assistance in their areas, so it is not only advantageous, but recommended to communicate with the community about your new patch. + +Typically bug fixes and new features start out as an idea or an experiment posted on one of [our forums](https://scala-lang.org/community/index.html#forums) to find out how people feel +about things you want to implement. People proficient in certain areas of Scala usually monitor forums and discussion rooms, so you'll often get some help by posting a message. +But the most efficient way to connect is to mention in your message one of the people responsible for maintaining the aspect of Scala which you wish to contribute to. + +A list of language features/libraries along with their maintainer's full names and GitHub usernames is [in the Scala repo README](https://github.com/scala/scala#get-in-touch). + +In our running example, since Martin is the person who submitted the string interpolation Scala Improvement Proposal and implemented this language feature for Scala 2.10.0, he might be interested in learning of new bugfixes to that feature. + +As alluded to earlier, one must also choose an appropriate avenue to discuss the issue. Typically, one would use the [Scala Contributor's Forum][contrib-forum], as there are post categories devoted to discussions about the core internal design and implementation of the Scala system. + +In this example, the issue was previously discussed on the (now unused) scala-user mailing list, at the time, +we would have posted to the [the (now unused) scala-user mailing list](https://groups.google.com/group/scala-user) about our issue: + +Posting to scala-user +Response from Martin + +Now that we have the approval of the feature's author, we can get to work! + +## 2. Set up + +Hacking Scala begins with creating a branch for your work item. To develop Scala we use [Git](https://git-scm.com/) +and [GitHub](https://github.com/). This section of the guide provides a short walkthrough, but if you are new to Git, +it probably makes sense to familiarize yourself with Git first. We recommend + +* the [Git Pro](https://git-scm.com/book/en/) online book. +* the help page on [Forking a Git Repository](https://help.github.com/articles/fork-a-repo). +* this great training tool [LearnGitBranching](https://pcottle.github.io/learnGitBranching/). One hour hands-on training helps more than 1000 hours reading. + +### Fork + +Log into [GitHub](https://github.com/), go to [https://github.com/scala/scala](https://github.com/scala/scala) and click the `Fork` +button in the top right corner of the page. This will create your own copy of our repository that will serve as a scratchpad for your work. + +If you're new to Git, don't be afraid of messing up-- there is no way you can corrupt our repository. + +Fork scala/scala + +### Clone + +If everything went okay, you will be redirected to your own fork at `https://github.com/user-name/scala`, where `username` +is your GitHub user name. You might find it helpful to read [https://help.github.com/fork-a-repo/](https://help.github.com/fork-a-repo/), +which covers some of the things that will follow below. Then, _clone_ your repository (i.e. pull a copy from GitHub to your local machine) by running the following on the command line: + + 16:35 ~/Projects$ git clone https://github.com/xeno-by/scala + Cloning into 'scala'... + remote: Counting objects: 258564, done. + remote: Compressing objects: 100% (58239/58239), done. + remote: Total 258564 (delta 182155), reused 254094 (delta 178356) + Receiving objects: 100% (258564/258564), 46.91 MiB | 700 KiB/s, done. + Resolving deltas: 100% (182155/182155), done. + +This will create a local directory called `scala`, which contains a clone of your own copy of our repository. The changes that you make +in this directory can be propagated back to your copy hosted on GitHub and, ultimately, pushed into Scala when your patch is ready. + +### Branch + +Before you start making changes, always create your own branch. Never work on the `master` branch. Think of a name that describes +the changes you plan on making. Use a prefix that describes the nature of your change. There are essentially two kinds of changes: +bug fixes and new features. + +* For bug fixes, use `issue/NNNN` or `ticket/NNNN` for bug `NNNN` from the [Scala bug tracker](https://github.com/scala/bug). +* For new feature use `topic/XXX` for feature `XXX`. Use feature names that make sense in the context of the whole Scala project and not just to you personally. For example, if you work on diagrams in Scaladoc, use `topic/scaladoc-diagrams` instead of just `topic/diagrams` would be a good branch name. + +Since in our example, we're going to fix an existing bug +[scala/bug#6725](https://github.com/scala/bug/issues/6725), we'll create a branch named `ticket/6725`. + + 16:39 ~/Projects/scala (master)$ git checkout -b ticket/6725 + Switched to a new branch 'ticket/6725' + +If you are new to Git and branching, read the [Branching Chapter](https://git-scm.com/book/en/Git-Branching) in the Git Pro book. + +### Build + +The next step after cloning your fork is setting up your machine to build Scala. + +You need the following tools: + +* A Java JDK. The baseline version is `8` for 2.13.x and higher. It's possible to use a higher JDK version for local development, but the continuous integration builds will verify against the baseline version. +* `sbt`, an interactive build tool commonly used in Scala projects. Acquiring sbt manually is not necessary -- the recommended approach is to download the [sbt-extras runner script](https://github.com/paulp/sbt-extras/blob/master/sbt) and use it in place of `sbt`. The script will download and run the correct version of sbt when run from the Scala repository's root directory. +* `curl` -- the build uses `curl` in the `pull-binary-libs.sh` script to download bootstrap libs. + +macOS and Linux builds should work. Windows is supported, but it might have issues. Please report to the [Scala 2 bug tracker](https://github.com/scala/bug) if you encounter any. + +Building Scala can be done with a single command `sbt dist/mkPack`, from the root of your cloned repository. In general, it's much more efficient to enter the `sbt` shell once and run the various tasks from there, instead of running each task by launching `sbt some-task` on your command prompt. + +Be prepared to wait for a while -- a full "clean" build takes 5+ minutes depending on your machine (longer on older machines with less memory). On a recent laptop, incremental builds usually complete within 10-30 seconds. + +### IDE + +There's no single editor of choice for working with Scala sources, as there are trade-offs associated with each available tool. + +IntelliJ IDEA has a Scala plugin, which is known to work with our codebase. Alternatively you can use Visual Studio Code with the [Metals IDE extension](https://marketplace.visualstudio.com/items?itemName=scalameta.metals). +Both of these Scala IDE solutions provide navigation, refactoring, error reporting functionality, and integrated debugging. +See [the Scala README](https://github.com/scala/scala#ide-setup) for instructions on using either IntelliJ IDEA or Metals with the Scala repository. + +Other alternative editors exist, such as Atom, Emacs, Sublime Text or jEdit. These are faster and much less memory/compute-intensive to run, but lack semantic services and debugging. + +We recognise that there exist preferences towards specific IDE/editor experiences, so ultimately we recommend that your choice be your personal preference. + +## 3. Hack + +When hacking on your topic of choice, you'll be modifying Scala, compiling it and testing it on relevant input files. +Typically you would want to first make sure that your changes work on a small example and afterwards verify that nothing break +by running a comprehensive test suite. + +We'll start by creating a `sandbox` directory (`./sandbox` is listed in the .gitignore of the Scala repository), which will hold a single test file and its compilation results. First, let's make sure that +[the bug](https://github.com/scala/bug/issues/6725) is indeed reproducible by putting together a simple test and compiling and running it with the Scala compiler that we built using `sbt`. The Scala compiler that we just built is located in `build/pack/bin`. + + 17:25 ~/Projects/scala (ticket/6725)$ mkdir sandbox + 17:26 ~/Projects/scala (ticket/6725)$ cd sandbox + 17:26 ~/Projects/scala/sandbox (ticket/6725)$ edit Test.scala + 17:26 ~/Projects/scala/sandbox (ticket/6725)$ cat Test.scala + object Test extends App { + val a = 1 + val s = f"$a%s%n$a%s" + println(s) + } + 17:27 ~/Projects/scala/sandbox (ticket/6725)$ ../build/pack/bin/scalac Test.scala + 17:28 ~/Projects/scala/sandbox (ticket/6725)$ ../build/pack/bin/scala Test + 1%n1 // %n should've been replaced by a newline here + +### Implement + +Now, implement your bugfix or new feature! + +Here are also some tips & tricks that have proven useful in Scala development: + +* After building your working copy with the `compile` sbt task, there's no need to leave the comfort of your sbt shell to try it out: the REPL is available as the `scala` task, and you can also run the compiler using the `scalac` task. If you prefer to run the REPL outside sbt, you can generate the scripts in `build/quick/bin` using the `dist/mkQuick` task. +* The sbt workflow is also great for debugging, as you can create a remote debugging session in your favorite IDE, and then activate the JVM options for the next time you run the `scala` or `scalac` tasks using: + +``` +> set javaOptions in compiler := List("-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8002") +> scalac test.scala +[info] Running scala.tools.nsc.Main -usejavacp test.scala +Listening for transport dt_socket at address: 8002 +``` + +* Also see [the Scala README](https://github.com/scala/scala#incremental-compilation) for tips on speeding up compile times. +* If after introducing changes or updating your clone, you get `AbstractMethodError` or other linkage exceptions, try the `clean` task and building again. +* Don't underestimate the power of using `println` to print debug information. When starting with Scala, I spent a lot of time in the debugger trying to figure out how + things work. However later I found out that print-based debugging is often more effective than jumping around. It's also useful to print stack traces to understand the flow of execution, for example what code executed before some action occurred. When working with `Trees`, you might want to use `showRaw` to get the `AST` representation. +* You can publish your newly-built scala version locally using the `publishLocal` task in sbt. +* It's convenient to enable the following local settings to speed up your workflow (put these in `local.sbt` in your working copy): + +``` +// skip docs for local publishing +publishArtifact in (Compile, packageDoc) in ThisBuild := false +// set version based on current sha, so that you can easily consume this build from another sbt project +baseVersionSuffix := s"local-${Process("tools/get-scala-commit-sha").lines.head.substring(0, 7)}" +// show more logging during a partest run +testOptions in IntegrationTest in LocalProject("test") ++= Seq(Tests.Argument("--show-log"), Tests.Argument("--show-diff")) +// if incremental compilation is compiling too much (should be fine under sbt 0.13.13) +// antStyle := true +``` + +* Adding a macro to the `Predef` object is a pretty involved task. Due to bootstrapping, it makes it more complex to add a macro. For this reason, the process is more involved. It could be useful to replicate the way `StringContext.f` itself is added. In short, you need to define your macro under `src/compiler/scala/tools/reflect/` and provide no implementation in `Predef` (it will look like `def fn = macro ???`). Now you have to set up the wiring. Add the name of your macro to `src/reflect/scala/reflect/internal/StdNames.scala`, add the needed links to it to `src/reflect/scala/reflect/internal/Definitions.scala`, and finally specify the bindings in `src/compiler/scala/tools/reflect/FastTrack.scala`. [Here's](https://github.com/folone/scala/commit/59536ea833ca16c985339727baed5d70e577b0fe) an example of adding a macro. + +### Where to Find Documentation + +The separate projects under Scala have varying amounts of documentation: + +##### The Scala Library + +Contributing to the Scala standard library is about the same as working on one of your own libraries. + +If documentation is necessary for some trait/class/object/method/etc in the Scala standard library, typically maintainers will include inline comments describing their design decisions or rationale for implementing things the way they have, if it is not straightforward. + +The Scala collections framework, part of the Scala standard library, is more complex. You should become familiar +with its architecture, which is documented in [the Architecture of Scala Collections][collections-arch]. +The [Scala Collections Guide][collections-intro] is more general, covering the synchronous portion of collections. For parallel collections, there also exists a detailed [Scala Parallel Collections Guide][collections-par]. + +##### The Scala Compiler + +Documentation about the internal workings of the Scala compiler is scarce, and most of the knowledge is passed around by forum ([Scala Contributors](https://contributors.scala-lang.org/) forum), chat-rooms (see `#scala-contributors` on [Discord][discord-contrib]), ticket, or word of mouth. However the situation is steadily improving. Here are the resources that might help: + +* [Compiler internals videos by Martin Odersky](https://www.scala-lang.org/old/node/598.html) are quite dated, but still very useful. In this three-video + series Martin explains the general architecture of the compiler, and the basics of the front-end, which later became the `scala-reflect` module's API. +* [Reflection documentation][reflect-overview] describes fundamental data structures (like `Tree`s, `Symbol`s, and `Types`) that + are used to represent Scala programs and operations defined on then. Since much of the compiler has been factored out and made accessible via the `scala-reflect` module, all of the fundamentals needed for reflection are the same for the compiler. +* [Scala compiler corner](https://lampwww.epfl.ch/~magarcia/ScalaCompilerCornerReloaded/) contains extensive documentation about + most of the post-typer phases (i.e. the backend) in the Scala compiler. +* [Scala Contributors](https://contributors.scala-lang.org/), a forum which hosts discussions about the core + internal design and implementation of the Scala system. + +##### Other Projects + +Tools like Scaladoc also welcome contributions. Unfortunately these smaller projects have less developer documentation. In these cases, the best thing to do is to directly explore the code base (which often contains documentation as inline comments) or to write to the appropriate maintainers for pointers. + +### Interlude + +To fix [the bug we're interested in](https://github.com/scala/bug/issues/6725) we've tracked the `StringContext.f` interpolator +down to a macro implemented in `MacroImplementations.scala` There we notice that the interpolator only processes conversions, +but not tokens like `%n`. Looks like an easy fix. + + 18:44 ~/Projects/scala/sandbox (ticket/6725)$ git diff + diff --git a/src/compiler/scala/tools/reflect/MacroImplementations.scala b/src/compiler/scala/tools/ + index 002a3fce82..4e8f02084d 100644 + --- a/src/compiler/scala/tools/reflect/MacroImplementations.scala + +++ b/src/compiler/scala/tools/reflect/MacroImplementations.scala + @@ -117,7 +117,8 @@ abstract class MacroImplementations { + if (!strIsEmpty) { + val len = str.length + while (idx < len) { + - if (str(idx) == '%') { + + def notPercentN = str(idx) != '%' || (idx + 1 < len && str(idx + 1) != 'n') + + if (str(idx) == '%' && notPercentN) { + bldr append (str substring (start, idx)) append "%%" + start = idx + 1 + } + +After applying the fix and running `sbt compile`, our simple test case in `sandbox/Test.scala` started working! + + 18:51 ~/Projects/scala/sandbox (ticket/6725)$ cd .. + 18:51 ~/Projects/scala (ticket/6725)$ sbt compile + ... + [success] Total time: 18 s, completed Jun 6, 2016 9:03:02 PM + Total time: 18 seconds + + 18:51 ~/Projects/scala (ticket/6725)$ cd sandbox + 18:51 ~/Projects/scala/sandbox (ticket/6725)$ ../build/pack/bin/scalac Test.scala + 18:51 ~/Projects/scala/sandbox (ticket/6725)$ ../build/pack/bin/scala Test + 1 + 1 // no longer getting the %n here - it got transformed into a newline + +### Test + +To guard your change against accidental breakage in the future, it is important to add tests. +I have already written one test earlier, so that's a good start but not enough! Apart from obvious usages of our new functionality, we need to cover corner-cases as well. + +Adding tests to the test suite is as easy as moving them to the appropriate directory: + +* Code which should compile successfully, but doesn't need to be executed, needs to go into the [“pos” directory](https://github.com/scala/scala/tree/2.12.x/test/files/pos). +* Code which should not compile needs to go into the [“neg” directory](https://github.com/scala/scala/tree/2.12.x/test/files/neg). +* Code which should compile and get executed by the test suite needs to go into the [“run” directory](https://github.com/scala/scala/tree/2.12.x/test/files/run) and have a corresponding `.check` file with the expected output. You will get test failures if the content of a `.check` file is different from what the test produces while running. If the change in the output is an expected product of your work, you might not want to change the `.check` file by hand. To make partest change the `.check` file, run it with a `--update-check` flag, like so `./test/partest --update-check path/to/test.scala`. For more information on partest, please refer to its [documentation](https://github.com/scala/scala-partest). +* Everything that can be unit-tested should go to ["junit" directory](https://github.com/scala/scala/tree/2.12.x/test/junit) +* Property-based tests go to the ["scalacheck" directory](https://github.com/scala/scala/tree/2.12.x/test/scalacheck) + +Here are some more testing tips: + +* If you have several tests, and want a tool for only running tests that conform to some regular expression, you can use `partest-ack` in the `tools` directory: `./tools/partest-ack "dottype"`. `partest-ack` was removed in 2.12. +* If you want to run all scalacheck tests from sbt use `scalacheck/testOnly` +* To run scalacheck tests by name when in sbt use `scalacheck/testOnly ... `, for example `scalacheck/testOnly scala.tools.nsc.scaladoc.HtmlFactoryTest` +* If your tests fail in the following way: + + test.bc: + [echo] Checking backward binary compatibility for scala-library (against 2.11.0) + [mima] Found 2 binary incompatibiities + [mima] ================================ + [mima] * synthetic method + [mima] scala$package$Class$method(java.lang.String)Unit in trait + [mima] scala.package.Class does not have a correspondent in old version + [mima] * synthetic method + [mima] scala$package$AnotherClass$anotherMethod(java.lang.String)Unit in trait + [mima] scala.package.AnotherClass does not have a correspondent in old version + [mima] Generated filter config definition + [mima] ================================== + [mima] + [mima] filter { + [mima] problems=[ + [mima] { + [mima] matchName="scala.package.Class$method" + [mima] problemName=MissingMethodProblem + [mima] }, + [mima] { + [mima] matchName="scala.package.AnotherClass$anotherMethod" + [mima] problemName=MissingMethodProblem + [mima] } + [mima] ] + [mima] } + [mima] + + ... + Finished: FAILURE + +This means your change is backward or forward binary incompatible with the specified version (the check is performed by the [migration manager](https://github.com/typesafehub/migration-manager)). The error message is actually saying what you need to modify `project/MimaFilters.scala` to make the error go away. If you are getting this on an internal/experimental api, it should be safe to add suggested sections to the config. Otherwise, you might want to target a newer version of scala for this change. + +### Verify + +Now to make sure that my fix doesn't break anything I need to run the test suite. The Scala test suite uses [JUnit](https://junit.org/junit4/) and [partest][partest-guide], a tool we wrote for testing Scala. +Run `sbt test` and `sbt partest` to run all of the JUnit and partest tests, respectively. +`partest` (not `sbt partest`) also allows you to run a subset of the tests using wildcards: + + 18:52 ~/Projects/scala/sandbox (ticket/6725)$ cd ../test + 18:56 ~/Projects/scala/test (ticket/6725)$ partest files/run/*interpol* + Testing individual files + testing: [...]/files/run/interpolationArgs.scala [ OK ] + testing: [...]/files/run/interpolationMultiline1.scala [ OK ] + testing: [...]/files/run/interpolationMultiline2.scala [ OK ] + testing: [...]/files/run/sm-interpolator.scala [ OK ] + testing: [...]/files/run/interpolation.scala [ OK ] + testing: [...]/files/run/stringinterpolation_macro-run.scala [ OK ] + All of 6 tests were successful (elapsed time: 00:00:08) + +## 4. Publish + +After development is finished, it's time to publish the code and submit your patch for discussion and potential inclusion into Scala. +In a nutshell, this involves: + +1. making sure that your code and commit messages are of high quality, +2. clicking a few buttons in the GitHub interface, +3. assigning one or more reviewers who will look through your pull request. + +Let's go into each of these points in more detail. + +### Commit + +The [Git Basics](https://git-scm.com/book/en/Git-Basics) chapter in the Git online book covers most of the basic workflow during this stage. +There are two things you should know here: + +1. Commit messages are often the only way to understand the intentions of authors of code written a few years ago. Thus, writing a quality is of utmost importance. The more context you provide for the change you've introduced, the larger the chance that some future maintainer understand your intentions. Consult [the pull request policies](https://github.com/scala/scala/blob/2.12.x/CONTRIBUTING.md) for more information about the desired style of your commits. +2. Keeping Scala's git history clean is also important. Therefore we won't accept pull requests for bug fixes that have more than one commit. For features, it is okay to have several commits, but all tests need to pass after every single commit. To clean up your commit structure, you want to [rewrite history](https://git-scm.com/book/en/Git-Branching-Rebasing) using `git rebase` so that your commits are against the latest revision of `master`. + +Once you are satisfied with your work, synced with `master` and cleaned up your commits you are ready to submit a patch to the central Scala repository. Before proceeding make sure you have pushed all of your local changes to your fork on GitHub. + + 19:22 ~/Projects/scala/test (ticket/6725)$ git add ../src/compiler/scala/tools/reflect/MacroImplementations.scala + 19:22 ~/Projects/scala/test (ticket/6725)$ git commit + [ticket/6725 3c3098693b] SI-6725 `f` interpolator now supports %n tokens + 1 file changed, 2 insertions(+), 1 deletion(-) + 19:34 ~/Projects/scala/test (ticket/6725)$ git push origin ticket/6725 + Username for 'https://github.com': xeno-by + Password for 'https://xeno-by@github.com': + Counting objects: 15, done. + Delta compression using up to 8 threads. + Compressing objects: 100% (8/8), done. + Writing objects: 100% (8/8), 1.00 KiB, done. + Total 8 (delta 5), reused 0 (delta 0) + To https://github.com/xeno-by/scala + * [new branch] ticket/6725 -> ticket/6725 + +### Submit + +Now, we must simply submit our proposed patch. Navigate to your branch in GitHub (for me it was `https://github.com/xeno-by/scala/tree/ticket/6725`) +and click the pull request button to submit your patch as a pull request to Scala. If you've never submitted patches to Scala, you will +need to sign the contributor license agreement, which [can be done online](https://www.lightbend.com/contribute/cla/scala) within a few minutes. + +Submit a pull request + +### Review + +After the pull request has been submitted, you need to pick a reviewer (usually the person you've contacted in the beginning of your +workflow) and be ready to elaborate and adjust your patch if necessary. In this example, we picked Martin, because we had such a nice chat on the mailing list: + +SAssign the reviewer + +## Merge + +After your reviewer is happy with your code (usually signaled by a LGTM — “Looks good to me”), your job is done. +Note that there can be a gap between a successful review and the merge, because not every reviewer has merge rights. In that case, someone else from the team will pick up your pull request and merge it. +So don't be confused if your reviewer says “LGTM”, but your code doesn't get merged immediately. + +[collections-arch]: {% link _overviews/core/architecture-of-scala-collections.md %} +[collections-intro]: {% link _overviews/collections-2.13/introduction.md %} +[collections-par]: {% link _overviews/parallel-collections/overview.md %} +[reflect-overview]: {% link _overviews/reflection/overview.md %} +[partest-guide]: {% link _overviews/contribute/partest-guide.md %} +[documentation]: {% link _overviews/contribute/documentation.md %} +[contrib-forum]: https://contributors.scala-lang.org/ +[discord-contrib]: https://discord.com/invite/scala diff --git a/_overviews/contribute/inclusive-language-guide.md b/_overviews/contribute/inclusive-language-guide.md new file mode 100644 index 0000000000..375d988158 --- /dev/null +++ b/_overviews/contribute/inclusive-language-guide.md @@ -0,0 +1,130 @@ +--- +title: Inclusive Language Guide +num: 2 +--- + +We are committed to providing a friendly, safe and welcoming environment for +all, regardless of age, body size, disability, ethnicity, sex characteristics, +gender identity and expression, level of experience, education, socio-economic +status, nationality, personal appearance, race, religion, sexual identity +and orientation, or other such characteristics. + +Language is a powerful vehicle of ideas and representations, and as such, can highlight, accentuate, or blur certain characteristics of the world. +Language -- in its use and structure -- may bias our perception of the world, sometimes to the disadvantage of some people. +Different language strategies have therefore been suggested to promote more inclusive forms of language, echoing the need for more equal treatment for all. + +This inclusive language guide is therefore intended to help us adopt a more inclusive way of communicating. +Although the present guide does not exhaustively cover all issues pertaining to non-inclusive language, it covers the most important issues we are currently aware of. + +Contributions made to the core Scala projects and their documentation -- including to this website -- should follow this guide. + +## Non gendered language + +The use of *He*, *Him*, *His*, *Man* and *Men* should be avoided. +Although these terms are intended to refer to any genders (male, female, other, unknown or irrelevant), they imply that the subject is male and therefore excludes all other genders. +Instead, use the singular *they*, as already used by famous authors like Jane Austen. + +Example of the use of singular they: + +> When a developer wants to contribute to a project, they open a pull request. + +Although *they* refers to a single person, we conjugate the verb with the plural form. +This is similar to the polite form of pronouns in certain languages, such as "Sie" in German or "vous" in French. + +When possible, avoid (combined) words that refer to a specific gender, and use gender-neutral alternatives instead. +For example: + +* *man* or *woman* -> *person* +* *chairman* -> *chairperson* + +## The words easy, simple, quick, and trivial + +What might be easy for you might not be easy for others. +The same applies to other words like *quick* or *simple*. +When used in the positive or superlative forms, try eliminating this word from sentences because usually the same meaning can be conveyed without it. + +Example of a positive form: + +> You can then simply execute the program with the `run` command. + +can be replaced with + +> You can then execute the program with the `run` command. + +without changing the meaning of the sentence. + +Example of a superlative form: + +> The foobar method is the easiest way to get started with our library. + +can be replaced with + +> We show here how to use the foobar method to get started with our library. + +However, the comparative form of these adjectives and adverbs can be used when relevant. + +Example of a comparative form: + +> The foobar method is quicker to get started with than the baz method. + +Similarly, the word *just* is usually redundant and can be removed without altering the meaning. + +Example: + +> You can just add these settings to your build. + +can be replaced with + +> You can add these settings to your build. + +Of course, every situation is different, and there may be cases where using "the easy words" is still the best thing to do. +In that case, it should be a deliberate decision to use them, taking the above considerations into account. + +## Specific loaded words + +Some words may have a derogatory connotation and/or have clear oppressive origins. +Avoid these words to the greatest extent possible, and use neutral alternatives instead. +Currently, the following words, used for common computer science concepts, are discouraged. +This list is neither comprehensive nor definitive, and it can evolve over time. + +* **blacklist/whitelist** \ + While the etymology of these words has no relation to racism, their use suggests an association between the color black and some form of badness or exclusion, and between the color white and some form of goodness or inclusion. + Prefer alternatives when possible. + Several alternatives have been proposed but none sticks as "the one". We suggest using the pair *excludelist*/*includelist*, as it is generic enough to replace all uses of *blacklist*/*whitelist*. +* **master/slave** \ + Never use *slave*. + Never use *master* in conjunction with *slave*. + Depending on the specific architecture, use one of the following alternatives instead: *controller*/*worker*, *primary*/*secondary*, *leader*/*follower*, etc. + When in doubt, if you cannot choose, *primary*/*secondary* is always a decent fallback. \ + When used with the meaning of *teacher*, *expert*, *guide*, or *reference*, the word *master* is not specifically discouraged. + For example, the term *Master of the arts* is acceptable. \ + Note: there exists a broader movement of using `main` instead of `master` as the default git branch, led by GitHub and the git project themselves, and which we encourage people to follow as well. +* **sanity check** \ + Prefer *confidence check*. +* **segregated** \ + Computer science concepts like the *interface segregation principle* and *segregated networks* present segregation as being desirable, instead of bad. + Prefer alternatives like *separation of concerns* and *segmented networks*. +* **guru** \ + While a *guru* initially refers to a respected spiritual leader, it also designates the chief of a sect. + Both are of a spiritual nature and are ambiguous. + If possible, use a more precise term such as *teacher* or *expert*. + +A good source with explainers and references can be found at [https://github.com/dialpad/inclusive-language](https://github.com/dialpad/inclusive-language). + +Keep in mind that your particular application domain may contain its own share of domain-specific loaded words. +We encourage you to research inclusive language guidelines applicable to your domain. + +You may want to use automated software like [In Solidarity](https://github.com/apps/in-solidarity) to steer contributors away from loaded words. + +## Backward compatibility + +Sometimes, we have existing code, APIs or commands that do not follow the above recommendations. +It is generally advisable to perform renamings to address the issue, but that should not be done to the detriment of backward compatibility (in particular, backward binary compatibility of libraries). +Deprecated aliases should be retained when possible. + +Sometimes, it is not possible to preserve backward compatibility through renaming; for example for methods intended to be overridden by user-defined subclasses. +In those cases, we recommend to keep the old names, but document (e.g., in Scaladoc comments) that they are named as they are for historical reasons and to preserve compatibility, and what their intended name should be. + +## See also + +* Our [code of conduct](https://scala-lang.org/conduct/). diff --git a/_overviews/contribute/index.md b/_overviews/contribute/index.md new file mode 100644 index 0000000000..da197e233e --- /dev/null +++ b/_overviews/contribute/index.md @@ -0,0 +1,68 @@ +--- +title: Introduction +num: 1 +--- + +### 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 of 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/partest-guide.md b/_overviews/contribute/partest-guide.md new file mode 100644 index 0000000000..c8eb5cbf02 --- /dev/null +++ b/_overviews/contribute/partest-guide.md @@ -0,0 +1,92 @@ +--- +title: Running the Test Suite +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. + +## Using sbt + +The test suite can be run from the sbt console with: + +``` +sbt:root> partest +``` + +You can get a summary of the usage by running `partest --help`. + +If you would like to run particular tests pass the test paths as arguments + +``` +sbt:root> partest test/files/pos/bounds.scala test/scaladoc/run/diagrams-base.scala +``` + +To run only the Scaladoc tests use `--srcpath` with the location of the tests + +``` +sbt:root> partest --srcpath scaladoc +``` + +## Using ant + +> Please note support for ant was removed on the 2.12 branch. + +The test suite can be run by using ant from the command line: + + $ ant test.suite + +## Standalone + +Please note the standalone scripts mentioned below were removed in 2.12.2. sbt is the preferred way to run the test suite. + +There are launch scripts `partest` and `partest.bat` in the `test` folder of the scala project. To have partest run failing tests only and print details about test failures to the console, you can use + + ./test/partest --show-diff --show-log --failed + +You can get a summary of the usage by running partest without arguments. + +* Most commonly you want to invoke partest with an option that tells it which part of the tests to run. For example `--all`, `--pos`, `--neg` or `--run`. +* You can test individual files by specifying individual test files (`.scala` files) as options. Several files can be tested if they are from the same category, e.g., `pos`. +* You can enable output of log and diff using the `-show-log` and `-show-diff` options. +* If you get into real trouble, and want to find out what partest does, you can run it with option `--verbose`. This info is useful as part of bug reports. +* Set custom path from where to load classes: `-classpath ` and `-buildpath `. +* You can use the `SCALAC_OPTS` environment variable to pass command line options to the compiler. +* You can use the `JAVA_OPTS` environment variable to pass command line options to the runner (e.g., for `run/jvm` tests). +* The launch scripts run partest as follows: + + scala -cp scala.tools.partest.nest.NestRunner + + Partest classes from a `quick` build, e.g., can be found in `./build/quick/classes/partest/`. + + Partest will tell you where it loads compiler/library classes from by adding the `partest.debug` property: + + scala -Dpartest.debug=true -cp scala.tools.partest.nest.NestRunner + + + +## ScalaCheck tests + +Tests that depend on [ScalaCheck](https://github.com/rickynils/scalacheck) can be added under folder `./test/files/scalacheck`. A sample test: + + import org.scalacheck._ + import Prop._ + + object Test { + val prop_ConcatLists = property{ (l1: ListInt, l2: ListInt) => + l1.size + l2.size == (l1 ::: l2).size + } + + val tests = List(("prop_ConcatLists", prop_ConcatLists)) + } + +## Troubleshooting + +### Windows + +Some tests might fail because line endings in the `.check` files and the produced results do not match. In that case, set either + + git config core.autocrlf false + +or + + git config core.autocrlf input diff --git a/_overviews/contribute/scala-internals.md b/_overviews/contribute/scala-internals.md new file mode 100644 index 0000000000..f3b1de54de --- /dev/null +++ b/_overviews/contribute/scala-internals.md @@ -0,0 +1,60 @@ +--- +title: Scala Contributors Forum +num: 9 +--- + +The [Scala Contributors Forum][scala-contributors] is where discussions about the Scala ecosystem +occur, from the perspectives of core compiler, documentation and library contributors. It features updates from the +Scala Center, along with technical and logistical discussions concerning bugs, bug fixes, documentation, improvements, +new features and other contributor related topics. + +> The now legacy [scala-internals mailing list](https://groups.google.com/d/forum/scala-internals) used to fulfil this +> purpose, but has since expanded to encompass more topics in the new [forum][scala-contributors]. + +## Coordinating on Scala Contributors + +Prior to commencing on contribution work on larger changes to the Scala project, it is recommended (but not required) +that you make a post on [Scala Contributors][scala-contributors] announcing your intention. +It's a great time to invite any help, advice or ask any questions you might have. It's also a great place to meet peers, +one of whom will probably be reviewing your contribution at some point. +For smaller bug fixes or documentation changes where the risk of effort duplication is minimal, you can skip this post. + +To help users to sort through the posts, we request that the following categories are applied when you start a +new post please: + +| Category | Topics | +|-----------------------------|---------------------------------------------------------------------| +| `Documentation` | Documentation, e.g. docs.scala-lang.org, API (scaladoc), etc. | +| `Compiler` | Bug reporting/fixing, Scala compiler discussions/issues | +| `Tooling` | Tools including sbt, IDE plugins, testing, scaladoc generator, etc. | +| `Scala Standard Library` | Core libraries | +| `Scala Platform` | Extension libraries | +| `Language Design` | Scala language feature discussions / informal proposals | +| `Scala Improvement Process` | Scala language feature formal proposals | +| `Meta Discourse` | Administrative/coordination topics | +| `Community` | Discussions about events, community organising | + +### Why It's a Good Idea + +While it is optional to announce your intentions/work items on [Scala Contributors][scala-contributors] before starting, it is recommended thing to do for a number of reasons: + +* To attempt to cut down on duplicate effort (i.e. to avoid two people working on the same bug at the same time without coordinating effort). +* Related to the above: to allow the compiler team and core committers to warn of or smooth over potential merge conflicts between separate bugs that might affect the same code. +* Potentially someone has already thought about or even worked on that issue or a related one, and has valuable insight +that might save you time (including warnings about what you might find and may want to avoid - perhaps one option +already tried lead to no benefit). +* You might find a group of impassioned individuals who want to volunteer and help you. You will have the momentum since +you posted first, so then it's up to you to decide if you want their help or not. +* Posting could start a dialog with a potential reviewer, smoothing the later stages of your contribution before +merging your changes. +* There are a lot of nice people waiting to talk to you on [Scala Contributors][scala-contributors], you might be +surprised how valuable and pleasant you find the experience of talking to them. + +Even if you do not wish to post on [Scala Contributors][scala-contributors], please feel welcome to make contributions +anyway, as posting to the forum is *not* criteria for it to be accepted. For smaller, self-contained bugs it is +especially less important to make a post, however larger issues or features take more time to consider accepting them. +For large contributions we strongly recommend that you do to notify of your intention, which will help you determine if +there is large community support for your change, making it more likely that your large contribution will accepted, +before you spend a long time implementing it. + +[scala-contributors]: https://contributors.scala-lang.org diff --git a/_overviews/contribute/scala-standard-library-api-documentation.md b/_overviews/contribute/scala-standard-library-api-documentation.md new file mode 100644 index 0000000000..a6c812b7e4 --- /dev/null +++ b/_overviews/contribute/scala-standard-library-api-documentation.md @@ -0,0 +1,126 @@ +--- +title: Contribute to API Documentation +num: 6 +--- + +This page is specific to API documentation contributions – that is, API +documentation for +[Scala's standard library](https://scala-lang.org/api/current/#package) – +sometimes referred to as Scaladoc contributions. + +For contributions to tutorial and guide-style documentation on +[docs.scala-lang.org][home], +see [Add New Guides/Tutorials][add-guides]. + +*Please note, these instructions cover documentation contributions Scala core +libraries only. For other Scala projects please check those projects for the +contribution steps and guidelines. Thank you.* + +## Overview + +Since API documentation is located in Scala source code files, the +process for contributing API documentation is similar to that of contributing bug-fixes +to the Scala code base, but without the requirement that there be an issue filed on GitHub +first. When forking/branching, it would help to use a `scaladoc/xxxx` branch name, where `xxxx` is a +descriptive, but short branch name (e.g. `scaladoc/future-object`). +However, if an issue *does* exist, please use `issue/NNNN`, where `NNNN` is the ticket number, +instead. + +If you would like to assist us, you can +[report missing/incorrect API documentation](#contribute-api-documentation-bug-reports), or +[contribute new API documentation](#contribute-new-api-documentation). + +## Contribute API Documentation Bug Reports + +One good way to contribute is by helping us to identify missing documentation. To do +this, [browse the current API documentation](https://www.scala-lang.org/api/current/) +and identify missing, incorrect or inadequate documentation. A good place to start is +package objects for important packages (these often get overlooked for documentation +and are a good place for API overviews). + +If you find an issue, please log it in the [Scala bug tracker](https://github.com/scala/bug), +(or else the [Scala 3 issue tracker](https://github.com/lampepfl/dotty/issues) for Scala 3 library additions) +**after making sure it is not already logged as an issue**. To help with +disambiguation, please use the following format for issue title: + +* Use an action describing the work required, e.g. **Add**, **Document**, **Correct**, **Remove**. +* Use the full package, class/trait/object/enum name (or state package object if + that is the case). +* Extremely short description of what to do. +* More detail can (and should) go into the issue description, including a short + justification for the issue if it provides additional detail. + +Here is an example of the title and description for an example API documentation issue: + +`Document scala.concurrent.Future object, include code examples` + +(note the explicit companion object called out in the title) + +and the description: + +> The methods on the `Future` companion object are critical +> for using Futures effectively without blocking. Provide code +> examples of how methods like `sequence`, `transform`, `fold` and +> `firstCompletedOf` should be used. + +In addition to following these conventions, please add `documentation` and +`community` labels to the issue, and put them in the `Documentation and API` +component so that they show up in the correct issue filters. + +## Contribute New API Documentation + +### Required Reading + +Please familiarize yourself with the following before contributing +new API documentation to save time, effort, mistakes and repetition. + +* [Forking the Repo][hackers-setup] - follow the setup steps through + the Branch section. If providing new documentation related to an existing GitHub issue, use `issue/NNNN` + or `ticket/NNNN` as the guide states. If providing API documentation with no associated + GitHub issue, use `scaladoc/xxxx` instead. +* [Scaladoc for library authors][scaladoc-lib-authors] + covers the use of scaladoc tags, markdown and other features. +* [Scaladoc's interface][scaladoc-interface] + covers all of the features of Scaladoc's interface, e.g. switching between + companions, browsing package object documentation, searching, token searches + and so on. +* Prior to commit, be sure to read + [A note about git commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) and the [Scala Project & Developer Guidelines](https://github.com/scala/scala/blob/2.11.x/CONTRIBUTING.md). + Some of this latter document will clearly not apply (like the sections on providing tests, + however see below for some special requirements for documentation). Do still read + the whole document though, and pay close attention to the title and commit + message formats, noting *present tense*, *length limits* and that it must merge + cleanly. Remember that the title of the pull request will become the commit + message when merged. **Also**, be sure to assign one or more reviewers to the PR, if this is + not possible for you, you could mention a user in **in the pull request comments**. + +### Extra Requirements for Scaladoc Documentation Commits + +Although some of the requirements for bug fix pull requests are not needed for +API documentation commits, here are the step by step requirements to ensure your API documentation +PR is merged in smoothly: + +* Any and all code examples provided should *be correct, compile and run* as + expected (ensure this in the REPL or your IDE). +* Spelling must be checked for all written language *and* code examples where + possible. Most editors have some spell checking feature available. Scala code + itself is permitted to not pass a spell-checker, however any written language + should be checked. If you can also use a grammar checker, it will help. We + *will* ask for spelling and grammar to be corrected before acceptance. +* You **must** also run `sbt doc`, fix any problems and check the formatting and + layout of your changes. Again, corrections will be required if formatting or + layout are inadequate. After running `sbt doc` the generated documents can be + found under the `build/scaladoc/` folders (probably in the `library` subdirectory + but maybe under the others depending on what section of the Scala source you + are working on). +* All of these steps are required to save time for both the reviewers and + contributors. It benefits everyone to ensure that the PR to merge process is + as smooth and streamlined as possible. + +Thanks for helping us improve the Scaladoc API documentation! + +[home]: {% link index.md %} +[add-guides]: {% link _overviews/contribute/add-guides.md %} +[hackers-setup]: {% link _overviews/contribute/hacker-guide.md %}#2-set-up +[scaladoc-lib-authors]: {% link _overviews/scaladoc/for-library-authors.md %} +[scaladoc-interface]: {% link _overviews/scaladoc/interface.md %} diff --git a/_overviews/contribute/tools.md b/_overviews/contribute/tools.md new file mode 100644 index 0000000000..77115d03ab --- /dev/null +++ b/_overviews/contribute/tools.md @@ -0,0 +1,80 @@ +--- +title: IDE and Build Tool Contributions +num: 11 + +# Projects list: +projects: + - title: sbt + description: The interactive build tool. + icon: https://www.scala-sbt.org/assets/sbt-logo.svg + link: https://github.com/sbt/sbt + homeLink: https://www.scala-sbt.org/ + issuesLink: https://github.com/sbt/sbt#issues-and-pull-requests + readmeLink: https://github.com/sbt/sbt/blob/0.13/README.md + contributingLink: https://github.com/sbt/sbt/blob/0.13/CONTRIBUTING.md + - title: Scaladoc Tool + description: (Contribute through scala/scala) + icon: https://avatars1.githubusercontent.com/u/57059?v=3&s=200 + link: https://github.com/scala/scala + homeLink: https://www.scala-lang.org/api + issuesLink: https://github.com/scala/bug/labels/scaladoc + readmeLink: https://github.com/scala/scala#welcome + contributingLink: /contribute/guide.html + - title: Partest + description: Scala Compiler/Library Testing (Contribute through scala/scala) + icon: https://avatars1.githubusercontent.com/u/57059?v=3&s=200 + link: https://github.com/scala/scala + homeLink: https://github.com/scala/scala + issuesLink: https://github.com/scala/scala/issues + readmeLink: https://github.com/scala/scala/blob/2.13.x/CONTRIBUTING.md#partest + contributingLink: + +projectsInNeed: + - title: Scoverage + description: Scala code coverage tool + icon: https://avatars1.githubusercontent.com/u/5998302?v=3&s=200 + link: https://github.com/scoverage/scalac-scoverage-plugin + homeLink: http://scoverage.org/ + issuesLink: https://github.com/scoverage/scalac-scoverage-plugin/issues + readmeLink: https://github.com/scoverage/scalac-scoverage-plugin/blob/master/README.md + contributingLink: https://groups.google.com/forum/#!forum/scala-code-coverage-tool +--- +## Contributing to IDE and Build Tools + +The links below are to a number of Scala build and IDE related projects that are important in the larger Scala space, and which welcome contributions. + +Since these tools are in separate projects, they may (and likely will) have their own rules and guidelines for contributing. You should also check the `README.md` and (if it's present) `CONTRIBUTING.md` files from the actual projects before contributing to them. + +Typically, issues for these projects will be reported and kept in the GitHub project issue tracker for that project rather than in the Scala bug tracker. + +Many of these projects have a chat room on Discord or Gitter (usually linked from their `README.md` or `CONTRIBUTING.md` files) which is a great place to discuss proposed work before starting. + +There are some projects in this section that are in +[particular need](#projects-in-particular-need) so please check those out +if you would like to help revive them. + +### Broken Links? + +Stuff changes. Found a broken link or something that needs updating on this page? Please, consider [submitting a documentation pull request](/contribute/documentation.html#updating-scala-langorg) to fix it. + +### Projects + +{% if page.projects.size > 0 %} +{% include contributions-projects-list.html collection=page.projects %} +{% else %} +There are no projects. +{% endif %} + +### Projects in Particular Need + +{% if page.projectsInNeed.size > 0 %} + +The following projects are important to the Scala community but are particularly in need of contributors to continue their development. + +{% include contributions-projects-list.html collection=page.projectsInNeed %} + +{% else %} + +There are no projects in particular need. + +{% endif %} diff --git a/contribute.md b/contribute.md index 1abb5e539c..02a8e4b8d7 100644 --- a/contribute.md +++ b/contribute.md @@ -1,9 +1,9 @@ --- -layout: contribute -title: Contribute +layout: singlepage-overview +title: Why Contribute to docs.scala-lang.org? --- -###### Heather Miller +###### A note from Heather Miller ## A Place to Build Documentation Together @@ -21,175 +21,6 @@ If we want Scala to be accessible to more programmers, clear, easy-to-find docum If you're interested in contributing to the Scala project in general, I argue that one of the most meaningful ways that you can, is to help us improve this transfer of information- let's make it easier and faster for people to _get_ core concepts, and to answer their own questions so they can progress to _Scala-proficient_ quickly. Each line that you contribute has the potential to affect the entire Scala community as a whole-- current, and future. -## About docs.scala-lang.org +## How Can I Contribute? -### Content - -Currently, the _types_ of documentation supported in this repository are: - -- **Guides/Overviews**: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview. -- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. -- **Cheatsheets**: Quick reference of Scala syntax and behaviors. - -### Implementation - -This documentation repository is open-source, it lives in [github repository](https://github.com/scala/docs.scala-lang), and is always contribution-ready. - -It's statically generated from [Markdown](https://en.wikipedia.org/wiki/Markdown) source using [Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](https://pages.github.com/). This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location. - -The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic syntax highlighting, without the need for any tags. - -Additionally [mdoc](https://github.com/scalameta/mdoc) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by mdoc. Note that only validation is done. The output files from mdoc are not used in the building of the tutorial. Use `mdoc` or `mdoc:fail` for your code blocks. - -## Submitting Docs - -For one to contribute a document, one must simply -[fork](https://help.github.com/articles/fork-a-repo/) the -[repo](https://github.com/scala/docs.scala-lang), write their article in -[Markdown](https://daringfireball.net/projects/markdown/syntax) (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](https://docs.scala-lang.org). - - --- - layout: overview - title: My Awesome Title - --- - - ## An h2 Header in Markdown - - And a paragraph, with a [link](https://www.scala-lang.org). - - One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo` - -Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you. - -### Criteria for Docs to be Accepted - -The goal of this documentation repository is to be tighter and more organized than other community-driven documentation platforms, like wikis. As such, any document pulled in for inclusion on [https://docs.scala-lang.org](https://docs.scala-lang.org) must: - -- **"fit in"** to the repository ( _i.e.,_ it should not be a complete duplicate of another article), -- **be polished** it must be thorough, complete, correct, organized, and "article-like" (personal programming notes don't quite fit.) -- **be maintained** if the document might require revisions from time to time, it should come with an owner - -If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the \#scala-contributors room [on Discord](https://discord.com/invite/scala) for any questions, concerns, clarifications, etc. - -## Document Templates - -
-

Note: These templates will soon change slightly as a result of necessary refactoring.

-
- -### Guides/Overviews - -A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separated-by-dashes.md`, and header: - - --- - layout: overview - title: YOUR TITLE - --- - -The rest of the document should, of course, be written in [Markdown](https://en.wikipedia.org/wiki/Markdown). - -At the moment, `RELEVANT-CATEGORY` corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future. - -If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 10 - --- - -A **single** document in the collection must contain a tag in the header, `outof`, that indicates the total number of documents in the large overview. Putting it on the last page in the overview is often best: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 15 - outof: 15 - --- - -Index pages, such as [https://docs.scala-lang.org/overviews/index.html](https://docs.scala-lang.org/overviews/index.html) are automatically generated, assuming documents are properly placed under the correct `RELEVANT-CATEGORY`. So, simply drop your document into the correct folder, and you're done. - -### Tutorials - -At the moment, a tutorial that can be logically placed on **one** page must be placed in the directory `tutorials/` with the file name in the format `title-separated-by-dashes.md`. For the moment, single-page tutorials use the same layout as single-page overviews: - - --- - layout: overview - title: YOUR TITLE - --- - -If you have a **multiple-page** tutorial, like in the case of multiple-page overviews, you must both specify an ordering for your document, and a name must be assigned to the collection of tutorial pages. For example, the following header is used for the [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html) series of tutorial articles: - - --- - layout: inner-page-no-masthead - title: YOUR TITLE - - tutorial: scala-tour - num: 4 - --- - -At the moment, only indexes for multiple-page tutorials are automatically generated. - -### Cheatsheets - -For now, cheatsheets are assumed to be in the form of tables. To contribute a cheatsheet, one must simply produce their cheatsheet as a Markdown table, with the following header: - - --- - layout: cheatsheet - title: YOUR TITLE - by: YOUR NAME - about: SOME TEXT ABOUT THE CHEAT SHEET. - --- - -### Code blocks - -The site build process uses [mdoc](https://scalameta.org/mdoc/) to typecheck -code snippets in markdown. This is a great way to ensure the code snippets that -you're including typecheck and are valid. Here are a few quick types to get -started. - -To get started, you can simply add `mdoc` behind `scala` when you are creating a -code block. The `mdoc` modifier here will make sure that `mdoc` runs the code -snippet and ensures that it's valid. - - ```scala mdoc - val a = 1 - ``` -If you have a snippet that you expect to fail, you can also account for this by -using `mdoc:fail` for a compile error `mdoc:crash` for a runtime-error. - - ```scala mdoc:fail - val b: String = 3 // won't compile - ``` -Keep in mind that a single file is all compiled as a single unit, so you can't -redefine a variable that was defined above in another code snippet. _However_ -there are a couple ways to get around this. Firstly, you can use the `mdoc:nest` -modifier with will wrap the snippet in a `scala.Predef.locally{...}`. This will -essentially "hide" the snippet from the others. Another way around this is to -use the `mdoc:reset` modifier, which _resets_ and forgets about everything up -above. Here is an example using the various modifiers. - - ```scala mdoc - import java.time.Instant - - def now() = Instant.now() - object Foo {} - ``` - - ```scala mdoc:nest - case class Foo(a: Int) // conflicts with Foo above, but it's nested so it's fine - ``` - - ```scala mdoc - val a = s"The time is ${now()}" // still have access to the now method from above - ``` - ```scala mdoc:reset - case class Foo(a: String) // forget the previous Foo's and start fresh - ``` - ```scala mdoc - val myFoo = Foo("hi") // now we only have access to the last Foo - ``` +Please read: [Add New Guides/Tutorials](/contribute/add-guides.html) diff --git a/index.md b/index.md index 7e778ec83c..5790ce8b7c 100644 --- a/index.md +++ b/index.md @@ -40,7 +40,7 @@ scala3-sections: description: "The Scala 3 language reference." icon: "fa fa-book" link: /scala3/reference/overview.html - - title: "Contribution Guide" + - 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 @@ -118,4 +118,8 @@ scala2-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 the Scala Project" + icon: "fa fa-cogs" + link: /contribute/ --- diff --git a/scala3/contribute-to-docs.md b/scala3/contribute-to-docs.md index 5a2a336440..d39ba71ec4 100644 --- a/scala3/contribute-to-docs.md +++ b/scala3/contribute-to-docs.md @@ -45,8 +45,8 @@ a tour presenting the migration tools, and detailed migration guides. - [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration) - [Issues](https://github.com/scala/docs.scala-lang/issues) -## Scala 3 Contribution Guide -The [Scala 3 Contribution Guide](/scala3/guides/contribution/contribution-intro.html) +## Scala 3 Contributing Guide +The [Scala 3 Contributing Guide](/scala3/guides/contribution/contribution-intro.html) contains a comprehensive overview over contribution to and internals of the Scala 3 compiler and libraries - [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) diff --git a/scala3/guides.md b/scala3/guides.md index 812cedb611..26110b10ba 100644 --- a/scala3/guides.md +++ b/scala3/guides.md @@ -18,7 +18,7 @@ guides: icon: birthday-cake url: "/scala3/guides/tasty-overview.html" description: "An overview over the TASTy format aimed at end-users of the Scala language." - - title: "Contribution Guide" + - title: "Scala 3 Contributing Guide" by: Jamie Thompson, Anatolii Kmetiuk icon: cogs url: "/scala3/guides/contribution/contribution-intro.html" diff --git a/scala3/index.md b/scala3/index.md index 7c741fd931..a34c19a1ca 100644 --- a/scala3/index.md +++ b/scala3/index.md @@ -40,7 +40,7 @@ sections: description: "The Scala 3 language reference." icon: "fa fa-book" link: /scala3/reference/overview.html - - title: "Contribution Guide" + - 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 diff --git a/scala3/new-in-scala3.md b/scala3/new-in-scala3.md index 9a1e9da872..af6d6111c1 100644 --- a/scala3/new-in-scala3.md +++ b/scala3/new-in-scala3.md @@ -11,7 +11,7 @@ changes. If you want to dig deeper, there are a few references at your disposal: - The [Syntax Summary][syntax-summary] provides you with a formal description of the new syntax. - The [Language Reference][reference] gives a detailed description of the changes from Scala 2 to Scala 3. - The [Migration Guide][migration] provides you with all of the information necessary to move from Scala 2 to Scala 3. -- The [Contribution Guide][contribution] dives deeper into the compiler, including a guide to fix issues. +- The [Scala 3 Contributing Guide][contribution] dives deeper into the compiler, including a guide to fix issues. ## What's new in Scala 3 Scala 3 is a complete overhaul of the Scala language. At its core, many aspects