|
1 | 1 | --- |
2 | 2 | title: Bug Reporting |
3 | | -layout: inner-page-no-masthead |
4 | 3 | # permalink: /contribute/bug-reporting-guide/ |
5 | | -includeTOC: true |
| 4 | +redirect_to: |
| 5 | + - https://docs.scala-lang.org/contribute/bug-reporting-guide.html |
6 | 6 | --- |
7 | | - |
8 | | -The Scala compiler and standard library bug tracker is located at [https://github.com/scala/bug](https://github.com/scala/bug). Before you submit a bug make sure that it is certainly a bug by following instructions in *Is it a Bug?*. |
9 | | - |
10 | | -## Is it a Bug? |
11 | | - |
12 | | -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: |
13 | | - |
14 | | - - **Library** bugs typically manifest themselves as run-time exceptions, or as *unexpected*/*unintuitive* behavior of Scala Standard Library methods. |
15 | | - - **Compiler** errors are manifested as compile time exceptions, unexpected behavior of your code at run time, or invalid behavior of the type system. |
16 | | - - **Reflection** are bugs that appear in the ‘scala.reflect’ package. For the *reflection* bugs , the same rules apply as for the *library* bugs. |
17 | | - - **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. |
18 | | - |
19 | | -If your issue is related to any of the following external projects, make sure to use its appropriate issue tracker: |
20 | | - |
21 | | - - [Akka](https://doc.akka.io/docs/akka/current/project/issue-tracking.html) |
22 | | - - [Play!](https://github.com/playframework/Play20/issues) |
23 | | - - [Slick](https://github.com/slick/slick/issues) |
24 | | - - [Scala IDE](https://scala-ide-portfolio.assembla.com/spaces/scala-ide/support/tickets) |
25 | | - - [sbt](https://github.com/sbt/sbt/issues) |
26 | | - |
27 | | -The following are generally considered to be bugs: |
28 | | - |
29 | | -- **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. |
30 | | -- **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. |
31 | | -- **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. |
32 | | - |
33 | | -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: |
34 | | - |
35 | | -* Make sure you minimize your problem. To correctly minimize the problem follow the following instructions: |
36 | | - |
37 | | - 1. Gradually take apart the offensive code snippet until you believe you have the simplest representation of your problem. |
38 | | - |
39 | | - 2. Ensure that you have decoupled your code snippet from any library that could be introducing the offensive behavior. One way to achieve this is to try to recompile the offensive 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. |
40 | | - |
41 | | - 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. |
42 | | - |
43 | | - 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 `ant`. |
44 | | - |
45 | | - 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. |
46 | | - |
47 | | -* 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](https://docs.scala-lang.org/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). |
48 | | - |
49 | | -In general, if you find yourself stuck on any of these steps, asking on [Scala Contributors](https://contributors.scala-lang.org/) can be helpful: |
50 | | - |
51 | | - - For unexpected behavior use the [Community Category](https://contributors.scala-lang.org/c/community). |
52 | | - - For compiler bugs use the [Compiler Category](https://contributors.scala-lang.org/c/compiler). |
53 | | - |
54 | | -* Examples of exceptions reported by the compiler which usually are not bugs: |
55 | | - 1. `StackOverflowError` is typically not a bug unless the stacktrace involves the internal packages of the compiler (like `scala.tools.nsc...`). Try to increase the Java stack size (`-Xss`), in most of the cases it helps. |
56 | | - 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`). |
57 | | - |
58 | | -## Reporting Confirmed Bugs is a Sin |
59 | | - |
60 | | -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. |
61 | | - |
62 | | -**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. |
63 | | - |
64 | | -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. |
65 | | - |
66 | | -## Creating a Bug Report |
67 | | - |
68 | | -Please make sure to fill in as many fields as possible. Make sure you've indicated the following: |
69 | | - |
70 | | - 1. **Exact Scala version** that you are using. For example, `2.10.1` or `2.11.0-RC`. If the bug happens in multiple versions indicate all of them. |
71 | | - 2. **The component** that is affected by the bug. For example, the Standard Library, Scaladoc, etc. |
72 | | - 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. |
73 | | - 4. **Running environment**. Are you running on Linux? Windows? What JVM version are you using? |
74 | | - |
75 | | -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?). |
76 | | - |
77 | | -### Description |
78 | | - |
79 | | -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: |
80 | | - |
81 | | - 1. Include a test case (minimized if possible) enabling us to reproduce the problematic behavior. Include your test case (and output) in proper formatting `{code}` blocks: |
82 | | - |
83 | | - {code}Here you put your classes{code} |
84 | | - |
85 | | - 2. The expected output. |
86 | | - 3. The actual output, including the stacktrace. |
87 | | - 4. Related discussion on the mailing lists, if applicable. |
88 | | - 5. If you have already looked into the issue provide interesting insights or proposals for fixing the issue. |
0 commit comments