Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update CONTRIBUTING #3960

Merged
merged 3 commits into from Feb 21, 2018
Merged
Changes from 1 commit
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -3,35 +3,70 @@
[Setup]: http://www.scala-sbt.org/release/docs/Getting-Started/Setup
[Issues]: https://github.com/sbt/sbt/issues
[sbt-dev]: https://groups.google.com/d/forum/sbt-dev
[sbt-contrib]: https://gitter.im/sbt/sbt-contrib
[Lightbend]: https://www.lightbend.com/
[subscriptions]: https://www.lightbend.com/platform/subscription
[327]: https://github.com/sbt/sbt/issues/327
[gitter]: https://gitter.im/sbt/sbt
[documentation]: https://github.com/sbt/website

Issues and Pull Requests
Support
=======

[Lightbend] sponsors sbt and encourages contributions from the active community. Enterprises can adopt it for mission critical systems with confidence because Lightbend stands behind sbt with commercial support and services.

For community support please [ask] on StackOverflow with the tag "sbt".

- State the problem or question clearly and provide enough context. Code examples and `build.sbt` are often useful when appropriately edited.
- There's also [Gitter sbt/sbt room][gitter], but Stackoverflow is recommended so others can benefit from the answers.

For professional support, [Lightbend], the maintainer of Scala compiler and sbt, provides:

- [Lightbend Subscriptions][subscriptions], which includes Expert Support
- Training
- Consulting

How to contribute to sbt
========================

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

- Help someone at work or online help their build problem.
- Answer StackOverflow questions.
- Create plugins that extends sbt's feature.
- 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.

Preliminaries
--------------
### Notes about Documentation

Documentation fixes and contributions are as much welcome as to patching the core. Visit [the website project][documentation] 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.

Where to get help and/or file a bug report
------------------------------------------
### Where to get help and/or file a bug report

sbt project uses GitHub Issues as a publicly visible todo list. Please open a GitHub issue only when asked to do so.
sbt project uses GitHub Issues as a publicly visible todo list. Please open a GitHub issue when you are 90% sure it's an actual bug.

- If you need help with sbt, please [ask] on StackOverflow with the tag "sbt" and the name of the sbt plugin if any.
- If you run into an issue, have an enhancement idea, or a general discussion, bring it up to [sbt-dev] Google Group first.
- If you have an enhancement idea, or a general discussion, bring it up to [sbt-contrib].
- If you need a faster response time, consider one of the [Lightbend subscriptions][subscriptions].

What to report
--------------
### What to report

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

@@ -81,10 +116,7 @@ Finally, thank you for taking the time to report a problem.
Pull Requests
-------------

### Branch to work against

Whether implementing a new feature, fixing a bug, or modifying documentation, please work against the latest development branch (currently, 1.0.x).
See below for instructions on building sbt from source.
See below for the branch to work against.

### Adding notes

@@ -111,73 +143,80 @@ Make sure you document each commit and squash them appropriately. You can use th
* Scala's documentation on [Git Hygiene](https://github.com/scala/scala/tree/v2.12.0-M3#git-hygiene)
* Play's documentation on [Working with Git](https://www.playframework.com/documentation/2.4.4/WorkingWithGit#Squashing-commits)

Documentation
-------------

Documentation fixes and contributions are as much welcome as to the source code itself. Visit [the website project](https://github.com/sbt/website) to learn about how to contribute.

Build from source
=================

1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source.
2. Get the source code.

$ git clone git://github.com/sbt/sbt.git
$ cd sbt
### Branch to work against

3. The default branch is the development branch [1.0.x](https://github.com/sbt/sbt/tree/1.0.x), which contains the latest code for the next major sbt release. To build a specific release or commit, switch to the associated tag. The tag for the latest stable release is [v0.13.13](https://github.com/sbt/sbt/tree/v0.13.13):
sbt uses two branches for development:

$ git checkout v0.13.13
- Development branch: `1.x` (this is also called "master")
- Stable branch: `1.$MINOR.x`, where `$MINOR` is current minor version (e.g. `1.1.x` during 1.1.x series)

Note that sbt is always built with the previous stable release. For example, the [1.0.x](https://github.com/sbt/sbt/tree/1.0.x) branch is built with 0.13.13 and the [v0.13.13](https://github.com/sbt/sbt/tree/v0.13.13) tag is built with 0.13.12.
If you're working on a bug fix, it's a good idea to start with the `1.$MINOR.x` branch. Since we can always safely merge from stable to `1.x`, but not other way around.

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

s/branch. Since we can/branch. We can/


4. To build the launcher and publish all components locally,
### Instruction to build all modules from source

$ sbt
> publishLocal
1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source.
2. Get the source code.

5. To use this locally built version of sbt, copy your stable `~/bin/sbt` script to `~/bin/xsbt` and change it to use the launcher jar at `<sbt>/launch/target/sbt-launch.jar`.
```
$ mkdir sbt-modules
$ cd sbt-modules
$ for i in sbt io util librarymanagement zinc; do \
git clone https://github.com/sbt/$i.git && (cd $i; git checkout -b 1.1.x origin/1.1.x)
done
$ cd sbt
$ ./sbt-allsources.sh
```

Directory `target` is removed by `clean` command. Second solution is using the artifact stored in the local ivy repository.
3. To build the launcher and publish all components locally,

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Isn't the launcher in a different repo, not described in these instructions?

This comment has been minimized.

Copy link
@eed3si9n

eed3si9n Feb 21, 2018

Author Member

You're right.


The launcher is located in:
```
$ ./sbt-allsources.sh
> ;{../io}/publishLocal; {../util}/publishLocal; {../librarymanagement}/publishLocal; {../zinc}/publishLocal

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Also need to publishBridgesAndSet 2.12.4 in the zinc project. I couldn't figure out how to do that via sbt-allsources.

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Can this documentation be replaced with a command alias in the build?

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

I tried:

sbt:sbtRoot> set commands ++= (commands in ProjectRef(uri("../zinc"), "zincCore")).value
[info] Defining commands
[info] The new value will be used by no settings or tasks.
[info] Reapplying settings...
^[[A[info] Set current project to sbtRoot (in build file:/Users/jz/code/sbt-modules/sbt/)

sbt:sbtRoot> publishBridgesAndSet 2.12.4
[error] Expected ID character
[error] Not a valid command: compilerInterface
[error] Expected project ID
[error] Expected configuration
[error] Expected ':'
[error] Expected key
[error] Not a valid key: compilerInterface (similar: compilerCache, compileOrder, compileIncSetup)
[error] compilerInterface/publishLocal
[error]                  ^

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Maybe we should be the command definition in a packaged .scala file in the zinc build so we can access it from the SBT build under sbt-all-sources.

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Okay, so this seems to work in the absence of a working + for this use case.

set {val p=ProjectRef(uri("../zinc"), "compilerBridge");  scalaVersion in p := (crossScalaVersions in p).value(0)}
{../zinc}compilerBridge/publishLocal

set {val p=ProjectRef(uri("../zinc"), "compilerBridge");  scalaVersion in p := (crossScalaVersions in p).value(1)}
{../zinc}compilerBridge/publishLocal

set {val p=ProjectRef(uri("../zinc"), "compilerBridge");  scalaVersion in p := (crossScalaVersions in p).value(2)}
{../zinc}compilerBridge/publishLocal


set {val p=ProjectRef(uri("../zinc"), "compilerBridge");  scalaVersion in p := (crossScalaVersions in p).value(3)}
{../zinc}compilerBridge/publishLocal

This comment has been minimized.

Copy link
@eed3si9n

eed3si9n Feb 21, 2018

Author Member

Here's what I was about to commit

  commands += Command.command("publishLocalAllModule") { state =>
    val extracted = Project.extract(state)
    import extracted._
    val sv      = get(scalaVersion)
    val projs   = structure.allProjectRefs
    val ioOpt   = projs find { case ProjectRef(_, id) => id == "ioRoot"; case _ => false }
    val utilOpt = projs find { case ProjectRef(_, id) => id == "utilRoot"; case _ => false }
    val lmOpt   = projs find { case ProjectRef(_, id) => id == "lmRoot"; case _ => false }
    val zincOpt = projs find { case ProjectRef(_, id) => id == "zincRoot"; case _ => false }
    (ioOpt   map { case ProjectRef(build, _) => "{" + build.toString + "}/publishLocal" }).toList :::
    (utilOpt map { case ProjectRef(build, _) => "{" + build.toString + "}/publishLocal" }).toList :::
    (lmOpt   map { case ProjectRef(build, _) => "{" + build.toString + "}/publishLocal" }).toList :::
    (zincOpt map { case ProjectRef(build, _) =>
      val zincSv = get(scalaVersion in ProjectRef(build, "zinc"))
      val csv = get(crossScalaVersions in ProjectRef(build, "compilerBridge")).toList
      (csv flatMap { bridgeSv =>
        s"++$bridgeSv" :: ("{" + build.toString + "}compilerBridge/publishLocal") :: Nil
      }) :::
      List(s"++$zincSv", "{" + build.toString + "}/publishLocal")
    }).getOrElse(Nil) :::
    List(s"++$sv", "publishLocal") :::
    state
  },

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

With that, and the other instructions, I was able to modify util to beautify the logging and compile a sample project:

⚡ sbt
[❆info] ❆Loading settings from gpg.sbt,idea.sbt ...
[❆info] ❆Loading global plugins from /Users/jz/.sbt/1.0/plugins
[❆info] ❆Updating ProjectRef(uri("file:/Users/jz/.sbt/1.0/plugins/"), "global-plugins")...
[❆info] ❆Done updating.
[❆info] ❆Compiling 2 Scala sources to /Users/jz/.sbt/1.0/plugins/target/scala-2.12/sbt-1.0/classes ...
[❆info] ❆Done compiling.
[❆info] ❆Loading project definition from /private/tmp/sbt-scratch/project
[❆info] ❆Updating ProjectRef(uri("file:/private/tmp/sbt-scratch/project/"), "sbt-scratch-build")...
[❆info] ❆Done updating.
[❆info] ❆Loading settings from build.sbt ...
[❆info] ❆Set current project to sbt-scratch (in build file:/private/tmp/sbt-scratch/)
[❆info] ❆sbt server started at local:///Users/jz/.sbt/1.0/server/d783f1fc400c8f31587a/sock
sbt:sbt-scratch> compile
[❆info] ❆Compiling 1 Scala source to /private/tmp/sbt-scratch/target/scala-2.13.0-M2/classes ...
[❆info] ❆Non-compiled module 'compiler-bridge_2.13.0-M2' for Scala 2.13.0-M2. Compiling...
[❆info] ❆  Compilation completed in 7.275s.
[❆info] ❆Done compiling.
[❆success] ❆Total time: 8 s, completed 21/02/2018 5:21:32 PM
> publishLocal
```

$HOME/.ivy2/local/org.scala-sbt/sbt-launch/0.13.9/jars/sbt-launch.jar
### Instruction to build just sbt

for v0.13.9 tag, or in:
If the change you are making is contained in sbt/sbt, you could publishLocal on sbt/sbt:

$HOME/.ivy2/local/org.scala-sbt/sbt-launch/0.13.10-SNAPSHOT/jars/sbt-launch.jar
```
$ sbt
> publishLocal
```

for the development branch.
### Using the locally built sbt

## Modifying sbt
To use the locally built sbt, set the version in `build.properties` file to `1.$MINOR.$PATCH-SNAPSHOT`, or pass it in as `-Dsbt-version` property.

1. When developing sbt itself, run `compile` when checking compilation only.
```
$ cd ../hello
$ sbt -Dsbt-version=1.1.2-SNAPSHOT
```

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Does this method differ from sbt -sbt-version? I was a bit confused by the subsequent message about the mismatch between the build.properties version and the active version which talked about the reboot command. So I went back to editing build.properties.. Perhaps just suggest that way of doing it (which should be familiar to people)

This comment has been minimized.

Copy link
@eed3si9n

eed3si9n Feb 21, 2018

Author Member

Yea. Let's keep it simple.

This comment has been minimized.

Copy link
@dwijnand

dwijnand Feb 21, 2018

Member

sbt.version is the sys prop to set, not sbt-version.


2. To use your modified version of sbt in a project locally, run `publishLocal`.
### Clearing out boot and local cache

3. After each `publishLocal`, clean the `~/.sbt/boot/` directory. Alternatively, if sbt is running and the launcher hasn't changed, run `reboot full` to have sbt do this for you.
When you run a locally built sbt, the JAR artifacts will be now cached under `$HOME/.sbt/boot/scala-2.12.4/org.scala-sbt/sbt/1.$MINOR.$PATCh-SNAPSHOT` directory. To clear this out run: `reboot dev` command from sbt's session of your test application.

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

"PATCh"


4. If a project has `project/build.properties` defined, either delete the file or change `sbt.version` to `1.0.0-SNAPSHOT`.
One drawback of `-SNAPSHOT` version is that it's slow to resolve as it tries to hit all the resolvers. You can workaround that by using a version name like `1.$MONIR.$PATCH-LOCAL1`. A non-SNAPSHOT artifacts will now be cached under `$HOME/.ivy/cache/` directory, so you need to clear that out using [sbt-dirty-money](https://github.com/sbt/sbt-dirty-money)'s `cleanLocal` task.

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

"MONIR"

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

You can workaround that by using a version name like 1.$MONIR.$PATCH-LOCAL1

Need instructions on how to pass that into the SBT build.


This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

... You can set this version with:

sbt> set version in ThisBuild := (version in ThisBuild).value.replaceAll("-SNAPSHOT",  "-LOCAL1")

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

Do you mean $HOME/.ivy/local/ here?

This comment has been minimized.

Copy link
@dwijnand

dwijnand Feb 21, 2018

Member

no I think the mistake is the suggestion should be to run cleanCache

This comment has been minimized.

Copy link
@retronym

retronym Feb 21, 2018

Member

I've just been incrementing my version number to reduce the cognitive load :)

## Diagnosing build failures
### Diagnosing build failures

Globally included plugins can interfere building `sbt`; if you are getting errors building sbt, try disabling all globally included plugins and try again.

Running Tests
=============
### Running Tests

sbt has an extensive test suite of Unit tests and Integration tests!
sbt has a suite of unit tests and integration tests, also known as scripted tests.

Unit / Functional tests
-----------------------
#### Unit / Functional tests

Various functional and unit tests are defined throughout the
project. To run all of them, run `sbt test`. You can run a single test
suite with `sbt testOnly`

Integration tests
-----------------
#### Integration tests

Scripted integration tests reside in `sbt/src/sbt-test` and are
written using the same testing infrastructure sbt plugin authors can
@@ -190,23 +229,11 @@ command. To run a single test, such as the test in

sbt "scripted project/global-plugin"

Please note that these tests run PAINFULLY slow if the version set in
`build.sbt` is set to SNAPSHOT, as every time the scripted test boots
up a test instance of sbt, remote mirrors are scanned for possible
updates. It is recommended that you set the version suffix to
`-devel`, as in `1.0.0-devel`.

Building Documentation
======================

The scala-sbt.org site documentation is a separate project [website](https://github.com/sbt/website). Follow [the steps in the README](https://github.com/sbt/website#scala-sbtorg) to generate the documentation.

Other notes for maintainers
---------------------------

Note for maintainers
====================
### Publishing VS Code Extensions

Publishing VS Code Extensions
-----------------------------

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

ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.