2020-07-03 13:08:14 +03:00
|
|
|
---
|
|
|
|
layout: developer-doc
|
|
|
|
title: Development & Contributing Guide
|
|
|
|
category: summary
|
|
|
|
tags: [summary,contributing]
|
|
|
|
---
|
|
|
|
|
2020-04-08 12:29:01 +03:00
|
|
|
# Development & Contributing Guide
|
2020-07-16 10:50:31 +03:00
|
|
|
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.
|
2020-04-07 08:04:45 +03:00
|
|
|
|
2020-04-08 12:13:58 +03:00
|
|
|
<br/>
|
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
## Reporting Issues
|
|
|
|
|
2020-07-16 10:50:31 +03:00
|
|
|
**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/luna/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/luna/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.
|
2020-03-05 08:25:00 +03:00
|
|
|
|
2020-04-08 12:13:58 +03:00
|
|
|
<br/>
|
|
|
|
|
2020-03-05 08:25:00 +03:00
|
|
|
## Development Environment
|
2020-07-16 10:50:31 +03:00
|
|
|
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
|
2020-03-05 08:25:00 +03:00
|
|
|
need the following setup:
|
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
- **The Rust Toolchain (nightly-2019-11-04)**
|
2020-05-14 14:27:52 +03:00
|
|
|
|
2020-07-16 10:50:31 +03:00
|
|
|
This project uses several features available only in the nightly Rust
|
|
|
|
toolchain. Please use the
|
2020-04-07 08:04:45 +03:00
|
|
|
[the Rust toolchain installer](https://rustup.rs) to install it:
|
2020-03-05 08:25:00 +03:00
|
|
|
|
|
|
|
```bash
|
|
|
|
rustup toolchain install nightly-2019-11-04 # Install the nightly channel.
|
2020-03-23 23:26:30 +03:00
|
|
|
rustup override set nightly-2019-11-04 # Set it as the default toolchain for this folder.
|
2020-03-05 08:25:00 +03:00
|
|
|
rustup component add clippy # Install the linter.
|
2020-04-08 12:16:32 +03:00
|
|
|
cargo install wasm-pack --version 0.8.1 # Install the wasm-pack toolkit.
|
2020-03-13 19:52:41 +03:00
|
|
|
cargo install cargo-watch # To enable ./run watch utility
|
2020-03-05 08:25:00 +03:00
|
|
|
```
|
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
- **Node and Node Package Manager LTS**
|
2020-05-14 14:27:52 +03:00
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
In order to build the web and desktop applications you will need
|
2020-07-16 10:50:31 +03:00
|
|
|
[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
|
2020-04-07 08:04:45 +03:00
|
|
|
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`.
|
2020-03-05 08:25:00 +03:00
|
|
|
|
2020-05-14 14:27:52 +03:00
|
|
|
- **(Optional) FlatBuffer compiler `flatc`**
|
|
|
|
|
2020-07-16 10:50:31 +03:00
|
|
|
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.
|
2020-05-14 14:27:52 +03:00
|
|
|
|
2020-07-07 14:23:03 +03:00
|
|
|
`flatc` must be in version *newer than 1.12* due to
|
2020-07-16 10:50:31 +03:00
|
|
|
[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
|
2020-07-07 14:23:03 +03:00
|
|
|
`build.rs` script of the `enso-protocol package.
|
2020-05-14 14:27:52 +03:00
|
|
|
|
2020-03-05 08:25:00 +03:00
|
|
|
<br/>
|
|
|
|
|
|
|
|
## Working with sources
|
2020-07-16 10:50:31 +03:00
|
|
|
Please note that you should not use a code auto-formatter in this codebase.
|
|
|
|
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
|
2020-07-01 17:17:40 +03:00
|
|
|
[Rust style guide 1](./contributing/style-guide.md)
|
|
|
|
and the [Rust style guide 2](https://dev.enso.org/docs/style-guide/rust.html)
|
2020-04-07 08:04:45 +03:00
|
|
|
before contributing to the codebase.
|
2020-03-05 08:25:00 +03:00
|
|
|
|
2020-05-07 17:19:38 +03:00
|
|
|
### Setting up Engine Services
|
2020-07-16 10:50:31 +03:00
|
|
|
IDE requires a service named Project Picker to be running in the background
|
|
|
|
on the local machine. The service, being part of the Enso Engine, currently
|
|
|
|
must be built from the sources on the
|
|
|
|
[enso repository](https://github.com/luna/enso). 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 Picker.
|
|
|
|
|
|
|
|
To run Project Picker, it must be first built — please follow the Enso
|
|
|
|
Engine
|
|
|
|
[contributing guidelines](https://github.com/luna/enso/blob/main/docs/CONTRIBUTING.md)
|
|
|
|
to obtain sources and necessary tools. When they are in place, the service
|
|
|
|
can be built and started by issuing the following command in the [enso
|
|
|
|
repository](https://github.com/luna/enso) root:
|
2020-05-07 17:19:38 +03:00
|
|
|
```
|
|
|
|
sbt -java-home $JAVA_HOME -J-Xss10M project-manager/run
|
|
|
|
```
|
|
|
|
|
|
|
|
Where `$JAVA_HOME` is the path where `graalvm-ce-java8-20.0.0` is located.
|
|
|
|
|
|
|
|
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 Picker service packages.
|
2020-03-05 08:25:00 +03:00
|
|
|
|
|
|
|
### Development
|
2020-07-16 10:50:31 +03:00
|
|
|
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:
|
2020-03-05 08:25:00 +03:00
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
- **Interactive mode**
|
2020-07-16 10:50:31 +03:00
|
|
|
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/debug` to open example demo scenes. 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
|
2020-04-07 08:04:45 +03:00
|
|
|
[wasm-pack](https://github.com/rustwasm/wasm-pack) and accept the same
|
2020-03-05 08:25:00 +03:00
|
|
|
[command line arguments](https://rustwasm.github.io/wasm-pack/book/commands/build.html).
|
|
|
|
|
2020-04-07 08:04:45 +03:00
|
|
|
- **Production mode**
|
2020-07-16 10:50:31 +03:00
|
|
|
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 packages will be located at
|
2020-04-07 08:04:45 +03:00
|
|
|
`app/dist/native`.
|
2020-03-05 08:25:00 +03:00
|
|
|
|
|
|
|
### Testing, Linting, and Validation
|
2020-07-16 10:50:31 +03:00
|
|
|
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:
|
2020-03-05 08:25:00 +03:00
|
|
|
|
|
|
|
- **Size Validation**
|
2020-07-16 10:50:31 +03:00
|
|
|
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
|
2020-07-21 23:28:20 +03:00
|
|
|
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.
|
2020-04-07 08:04:45 +03:00
|
|
|
|
2020-03-05 08:25:00 +03:00
|
|
|
- **Testing**
|
2020-05-01 01:35:46 +03:00
|
|
|
For the test suite to run you need a current version of Chrome installed.
|
2020-03-05 08:25:00 +03:00
|
|
|
Use `node ./run test` run both unit and web-based visual test.
|
2020-06-15 20:11:36 +03:00
|
|
|
|
2020-05-01 01:35:46 +03:00
|
|
|
- *Note for Windows users*:
|
2020-07-16 10:50:31 +03:00
|
|
|
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`.
|
2020-04-07 08:04:45 +03:00
|
|
|
|
|
|
|
- **Linting**
|
2020-07-16 10:50:31 +03:00
|
|
|
Please be sure to fix all errors reported by `node ./run lint` before
|
|
|
|
creating a pull request to this repository.
|