Troubleshooting a failure

You can ask for help with any of this on Discord or Discourse, or open an issue.

When is this page applicable? Who is it for?

The advice on this page is about what to do when a particular project is failing because of a real issue or incompatibility in the code or a possible regression in Scala.

It's aimed not just at community build maintainers, but at external library maintainers and contributors who aren't really familiar with the community build but want to help diagnose and fix a failure.

More general information is on Maintenance; there is some overlap between that page and this.

Get oriented

Suppose a project is failing and the problem is a compilation failure or test failure that isn't the result of a missing dependency.

To initially get oriented:

• find the project's config in proj/foo.conf and read it, there may be useful comments, and it may be useful to know how we've customized the project's build, if it all
• also look at proj/foo.conf to see what branch or tag or whatever we’re using
  • if the community build is currently frozen, you'll only see a SHA rather than branch or tag information. in this case, consult the git history to see what branch or tag was being used before the freeze happened

Choose a troubleshooting method

Now you have a choice: do your work in dbuild, or outside dbuild?

Outside may be easier and more natural for you if you know nothing about dbuild and prefer to avoid learning it if possible, but has drawbacks.

Option 1: Outside of dbuild

This is a workable option if:

• the project in question has only one or two fully-versioned dependencies
• publishing those fully-versioned dependencies locally doesn't involve weird hassles

If you go this route, you publish those dependencies locally for the Scala version you’re working with, and you’re good to go, it's normal development work otherwise. https://stackoverflow.com/questions/40622878/how-do-i-tell-sbt-to-use-a-nightly-build-of-scala-2-12-or-2-13 explains how to use a nightly Scala build during publishing and troubleshooting.

If you're unable to reproduce the problem the community build sees, or if local publishing proves too much hassle, you'll have to switch to the dbuild route.

Option 2: Within dbuild

Choose this option if you're already comfortable with dbuild, or if option 1 doesn't work out.

Local runs explains how to run the community build locally. Read that first. In short, you just ./run or e.g. version=2.13.2-bin-abcd123 ./run if the Scala version in nightly.properties isn't the one you want.

Note the advice on that page about using the narrow script to work on only a subset of the full build. This can be a huge time-saver.

Actually doing the troubleshooting

If you need to make changes to a project’s code, then fork the project and push your changes to a branch in your fork, and change the projects proj/foo.conf file to point to your fork, and ./run myproject.

Another possibility is to use dbuild’s feature where you can ask dbuild to run, then pause and open sbt for you in the project you care about, using all of the actual settings and dependencies in the actual context of the build. This feature is documented at https://lightbend-labs.github.io/dbuild/0.9.20/introduction.html#what-if-the-build-fails . There isn't much to know, you just issue the magic dbuild checkout command with the right arguments.

I don’t generally use dbuild checkout for “normal” work, but for difficult debugging/troubleshooting, it can be a lifesaver, it cuts your turnaround time on code changes (as opposed to build config changes) down to almost nothing.

Example

let's take Akka for example, a sample session looks like:

hub clone scala/community-build
cd community-build
git checkout 2.13.x
./narrow akka
./run akka

suppose there are test failures, at the end you would see something like:

[akka] [error] Error: Total 1074, Failed 64, Errors 1, Passed 1009, Ignored 1, Pending 1
[akka] [error] Failed tests:
...
The repeatable UUID of this build was: e30be73033236284f66b4b246b2b9ab802ed13b2

so then to troubleshoot, you follow with:

./dbuild-0.9.20/bin/dbuild checkout e30be73033236284f66b4b246b2b9ab802ed13b2 akka akka-wip
./akka-wip/.dbuild/start

and then from the sbt prompt:

akka-actor-tests/test

or whatever other sbt commands you want to issue, at this point you're in normal sbt. dbuild-build will run all the exact same stuff the community build would. normal commands like akka-actor-tests/test are fine to issue as well

you can also make source code changes in the akka-wip directory and test them like normal.