enso/gui/docs/CONTRIBUTING.md

---
layout: developer-doc
title: Development & Contributing Guide
category: summary
tags: [summary,contributing]
---

# Development & Contributing Guide
Thank you for your interest in contributing to the Enso IDE! We believe that
only through community involvement can Enso be the best it can be! There are
a whole host of ways to contribute, and every single one is appreciated.

<br/>

## Reporting Issues

**If you are concerned that your bug publicly presents a security risk to
the users of Enso, please contact 
[security@enso.org](mailto:security@enso.org).**

While it's never great to find a bug, they are a reality of software and
software development! We can't fix or improve on the things that we don't
know about, so report as many bugs as you can! If you're not sure whether
something is a bug, file it anyway!

Even though GitHub search can be a bit hard to use sometimes, we'd
appreciate if you could
[search](https://github.com/enso-org/enso/search?q=&type=Issues&utf8=%E2%9C%93)
for your issue before filing a bug as it's possible that someone else has
already reported the issue. We know the search isn't the best, and it can be
hard to know what to search for, so we really don't mind if you _do_ submit 
a duplicate!

Opening an issue is as easy as following 
[this link](https://github.com/enso-org/ide/issues/new?template=bug-report.md)
and filling out the fields. The template is intended to collect all the
information we need to best diagnose the issue, so please take the time to
fill it out accurately.

The reproduction steps are particularly important, as the more easily we can
reproduce it, the faster we can fix the bug! It's also helpful to have the
version of the IDE, as that will let us know if the bug is Operating System
or Architecture specific.

<br/>

## Development Environment
The project builds on MacOS, Windows, and Linux. Cross-platform targets work
well on all of these platforms, however, MacOS package will miss the right
application icon if built on Linux or Windows due to non-trival icon
generation on these platforms. In order to develop the source code you will
need the following setup:

- **The Rust Toolchain (nightly-2019-11-04)**

  This project uses several features available only in the nightly Rust
  toolchain.  Please use the
  [the Rust toolchain installer](https://rustup.rs) to install it:

  ```bash
  rustup toolchain install nightly-2019-11-04 # Install the nightly channel.
  rustup component add clippy                 # Install the linter.
  cargo install wasm-pack --version 0.8.1     # Install the wasm-pack toolkit.
  cargo install cargo-watch                   # To enable ./run watch utility
  ```

- **Node and Node Package Manager LTS**

  In order to build the web and desktop applications you will need
  [the latest LTS version of node and npm](https://nodejs.org/en/download). Even
  minor release changes are known to cause serious issues, thus **we provide
  support for the latest LTS version only. Please do not report build issues
  if you use other versions.** In case you run run MacOS or
  Linux the easiest way to set up the proper version is by installing the
  [Node Version Manager](https://github.com/nvm-sh/nvm) and running
  `nvm install --lts && nvm use --lts`.

- **(Optional) FlatBuffer compiler `flatc`**

  This dependency is needed only if you need to update files generated by
  the FlatBuffer from the Engine Services binary protocol description.
  Otherwise, relying on the generated files that are being stored in this
  repository is fine.

  `flatc` must be in version *newer than 1.12* due to 
  [this bug](https://github.com/google/flatbuffers/issues/5055). As of
  writing this text there are no official releases with this issue fixed,
  however current binaries can be obtained from the project's CI 
  [build artifacts](https://github.com/google/flatbuffers/actions?query=branch%3Amaster). 
  `flatc` builds from 8 May 2020 onwards have been confirmed to work.

  After placing `flatc` in `PATH` you need to define the
  `ENSO_IDE_ENABLE_FLATC` environment variable to explicitly enable
   regeneration of the interface files. The `flatc` is run as part of
  `build.rs` script of the `enso-protocol package.

<br/>

## Working with sources
Please note that you should not use `cargo fmt` on this code base.
Please read the following documents to learn more about reasons behind this
decision and the recommended code style guide. Be sure to carefully read the
[Rust style guide 1](./contributing/style-guide.md)
and the [Rust style guide 2](https://dev.enso.org/docs/style-guide/rust.html)
before contributing to the codebase.

We do, however, use [`prettier`](https://prettier.io/) for the JavaScript files in our code base. 
If you have not installed it already you can do so via `npm install prettier`. To use it manually 
via command line run `prettier --write` to all JavaScript files in the project. Alternatively, 
there are plugins for many IDEs available to do this for you.

### Setting up Engine Services
IDE requires a service named Project Manager to be running in the background
on the local machine. The service, being part of the Enso Engine, can be
downloaded from [per-commit builds](https://github.com/enso-org/enso/actions?query=workflow%3A"Engine+CI"+branch%3Amain).
The minimal supported version is commit 
[d80089ab6916f86d0b8ce479438520f24a2ae345](https://github.com/enso-org/enso/actions/runs/399967504).

If the service is not running,the IDE will not start. However, it is possible 
to hack on many components of the IDE without the service. The debug scenes 
and tests will work even without the Project Manager.

The Project Manager requires to be run with the GraalVM version `20.2.0` and it 
must be the Java 11 build. You can download it from [here](https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-20.2.0),
and install according to the [instructions](https://www.graalvm.org/docs/getting-started-with-graalvm/#install-graalvm).
Remember to set `$PATH` and `$JAVA_HOME` to the GraalVM installation directory.

In future significant improvements to this process are planned, specifically:
* not requiring the engine to be able to start the IDE;
* providing self-contained Project Manager service packages.

### Development
As this is a multi-part project with many complex dependencies, it is
equipped with a build script which both validates your working environment as
well as takes care of providing the most suitable compilation flags for a
particular development stage. In order to run the build script simply run
`node ./run` in the root of the codebase. On MacOS and Linux you can use a
simpler form of `./run`, however, this doc will use the former form in order
to stay cross-platform compatible. Run `node ./run help` to learn about
available commands and options. All arguments provided after the `--` symbol
will be passed to sub-commands. For example `node ./run build -- --dev` will 
pass the `--dev` flag to `cargo` (Rust build tool). The most common options
are presented below:

- **Interactive mode**
  Run `node ./run watch` to start a local web-server and a source-file watch
  utility which will build the project on every change. Open 
  `http://localhost:8080` (the port may vary and will be reported in the
  terminal if `8080` was already in use) to run the application, or
  `http://localhost:8080/?entry` to open example demo scenes list. Please 
  remember to disable the cache in your browser during the development! By 
  default, the script disables heavyweight optimizations to provide interactive
  development experience. The scripts are thin wrappers for
  [wasm-pack](https://github.com/rustwasm/wasm-pack) and accept the same
  [command line arguments](https://rustwasm.github.io/wasm-pack/book/commands/build.html).

- **Production mode**
  In order to compile in a production mode (enable all optimizations, strip
  WASM debug symbols, minimize the output binaries, etc.), run 
  `node ./run build`. To create platform-specific packages and installers use
  `node ./run dist` instead. The final executables will be located at
  `dist/client/$PLATFORM`. 
  
- **Selective mode**
  In order to compile only part of the project, and thus drastically shorten 
  the incremental compile time, you are advised to use the selective 
  compilation mode by passing the `--crate` option to the `build` or `watch`
  command, e.g. `node ./watch --crate ensogl/example` to compile only the 
  renderer-related example scenes. Please note, that in order to run a scene
  in a web-browser, the scene has to be compiled and has to expose a public
  function with a name starting with `entry_point_`. Thus, if you compile 
  only selected crate, you will have access only to the example scenes that
  were defined or re-exported by that crate. In particular, the `ide` crate
  exposes the `entry_point_ide` function, so you have to compile it to test
  your code in the Enso IDE.
  
  
### Using IDE as a library.
In case you want to use the IDE as a library, for example to embed it into 
another website, you need to first build it using `node ./run {built,dist}` and 
find the necessary artifacts located at `dist/content`. Especially, the 
`dist/content/index.js` defines a function `window.enso.main(cfg)` which you
can use to run the IDE. Currently, the configuration argument can contain the
following options:
- `entry` - the entry point, one of predefined scenes. Set it to empty string to
  see the list of possible entry points.
- `project` - the project name to open after loading the IDE.


### Testing, Linting, and Validation
After changing the code it's always a good idea to lint and test the code. We 
have prepared several scripts which maximally automate the process:

- **Size Validation**
  Use `node ./run check-size` to check if the size of the final binary did
  not grew too much in comparison to the previous release. Watching the
  resulting binary size is one of the most important responsibility of each
  contributor in order to keep the project small and suitable for web-based
  usage. In case the size will exceed the limits:
  - If the PR does not include any new libraries, you are allowed to increase 
    the limit by 10KB. In case the limit will be exceeded by more than 10KB,
    check which part of the code contributet to it, and talk about it with the 
    code owner.
  - If the PR does include new libraries, you are allowed to increase the
    limit by 10KB, but you should also consider if it is possible to get the
    same results without using a new library (even by implementing few lines 
    of code from the library in sources of the project).
  - If the PR does include new libraries, and the limit is exceeded by more
    than 10KB, check which part of the code contributed to it, and talk about 
    it with the code owner.
  - If the PR does include new libraries, and the limit is exceeded by more 
    than 50KB, it would probably not be merged. Research possible alternatives
    before talking with code owner about this case.

- **Testing**
  For the test suite to run you need a current version of Chrome installed.
  Use `node ./run test` run both unit and web-based visual test.

  - *Note for Windows users*:
    there is a [known issue with wasm-pack](https://github.com/rustwasm/wasm-pack/issues/611) 
    using the wrong version of the chrome driver. There is
    [a workaround](https://github.com/rustwasm/wasm-pack/issues/611#issuecomment-522093207) 
    described in the issue: download compatible ChromeDriver from the
    [official source](https://chromedriver.chromium.org/downloads) and ensure it 
    is in your `PATH`.

- **Linting**
  Please be sure to fix all errors reported by `node ./run lint` before
  creating a pull request to this repository.