Skip to content

Latest commit

 

History

History
160 lines (104 loc) · 5.23 KB

CONTRIBUTING.md

File metadata and controls

160 lines (104 loc) · 5.23 KB
Raw

Contributing

(For support, see SUPPORT)

There are lots of ways to contribute to sbt ecosystem depending on your interests and skill level.

  • Help someone at work or online fix their build problem.
  • Answer StackOverflow questions.
  • Ask StackOverflow questions.
  • Create plugins that extend sbt's features.
  • Maintain and update documentation.
  • Garden the issue tracker.
  • Report issues.
  • Patch the core (send pull requests to code).
  • On-ramp other contributors.

Issues and Pull Requests

When you find a bug in sbt we want to hear about it. Your bug reports play an important part in making sbt more reliable and usable.

Effective bug reports are more likely to be fixed. These guidelines explain how to write such reports and pull requests.

Please open a GitHub issue when you are 90% sure it's an actual bug.

If you have an enhancement idea, or a general discussion, bring it up to sbt-contrib.

Notes about Documentation

Documentation fixes and contributions are as much welcome as to patching the core. Visit sbt/website to learn about how to contribute.

Preliminaries

  • Make sure your sbt version is up to date.
  • Search StackOverflow and Issues to see whether your bug has already been reported.
  • Open one case for each problem.
  • Proceed to the next steps for details.

What to report

The developers need three things from you: steps, problems, and expectations.

The most important thing to remember about bug reporting is to clearly distinguish facts and opinions.

Steps

What we need first is the exact steps to reproduce your problems on our computers. This is called reproduction steps, which is often shortened to "repro steps" or "steps." Describe your method of running sbt. Provide build.sbt that caused the problem and the version of sbt or Scala that was used. Provide sample Scala code if it's to do with incremental compilation. If possible, minimize the problem to reduce non-essential factors.

Repro steps are the most important part of a bug report. If we cannot reproduce the problem in one way or the other, the problem can't be fixed. Telling us the error messages is not enough.

Problems

Next, describe the problems, or what you think is the problem. It might be "obvious" to you that it's a problem, but it could actually be an intentional behavior for some backward compatibility etc. For compilation errors, include the stack trace. The more raw info the better.

Expectations

Same as the problems. Describe what you think should've happened.

Notes

Add any optional notes section to describe your analysis.

Subject

The subject of the bug report doesn't matter. A more descriptive subject is certainly better, but a good subject really depends on the analysis of the problem, so don't worry too much about it. "StackOverflowError while name hashing is enabled" is good enough.

Formatting

If possible, please format code or console outputs.

On GitHub it's:

```scala
name := "foo"
```

On StackOverflow, it's:

<!-- language: lang-scala -->

    name := "foo"

Here's a simple sample case: #327. Finally, thank you for taking the time to report a problem.

Pull Requests

See below for the branch to work against.

Adding notes

Most pull requests should include a "Notes" file which documents the change. This file should reside in the directory:

<sbt root>
  notes/
    <target release>/
       <your-change-name>.md

Notes files should have the following contents:

  • Bullet item description under one of the following sections:
    • ### Bug fixes
    • ### Improvements
    • ### Fixes with compatibility implications
  • Complete section describing new features.

Clean history

Make sure you document each commit and squash them appropriately. You can use the following guides as a reference:

Build from source

See DEVELOPING

Profiling sbt

See PROFILING

Other notes for maintainers

Publishing VS Code Extensions

Reference https://code.visualstudio.com/docs/extensions/publish-extension

$ sbt
> vscodePlugin/compile
> exit
cd vscode-sbt-scala/client
# update version number in vscode-sbt-scala/client/package.json
$ vsce package
$ vsce publish

Signing the CLA

Contributing to sbt requires you or your employer to sign the Lightbend Contributor License Agreement.

To make it easier to respect our license agreements, we have added an sbt task that takes care of adding the LICENSE headers to new files. Run headerCreate and sbt will put a copyright notice into it.