kitto

```
-> Work in progress <-
```

This document is a guide for new contributors, it's aimed in making
development easier and straightforward and document all important parts
of the current release practices.

## Prior knowledge required

You are expected to be familiar with the technologies used in the project
(Elixir, Mix, React, Webpack).

## Where to ask for help

If for any reason you get stuck, feel free to discuss on 
[gitter.im/kittoframework](https://gitter.im/kittoframework/Lobby).

## Structure of the project

Kitto consists of 3 core parts:

* Server
* Generator Tasks (mix kitto.new, mix kitto gen.job, mix kitto.install, ..)
* The JavaScript library and bundled widgets

The documentation concerning the backend (server, tasks) is available
at: [https://hexdocs.pm/kitto/][hexdocs].

## How to develop Kitto - Server

This section is about providing guidance for the development of the
server part of the framework.

You have successfully cloned the [kittoframework/kitto][kitto-repo] locally and have
started tweaking files to adapt them towards your goal.
You will want to try your changes in an actual Kitto dashboard application.
Your next step will be to setup a dashboard application to try your
changes.

You can scaffold a new dashboard app using:

```bash
mix kitto.new kittodev
```

or clone the demo dashboard:

```bash
git clone git@github.com:kittoframework/demo.git
```

Then you have to change the Mix dependency to point to the path of you
local kitto repo.

```elixir
defmodule Demo.Mixfile do
  use Mix.Project

  def project do
    # body omitted
  end

  def application do
    # body omitted
  end

  defp deps do
    [{:kitto, path: "~/dev/kitto"},  # Change this line to point to you kitto dev path
     {:httpoison, "~> 0.9", override: true},
     {:poison, "3.0.0", override: true}]
  end
end
```

To test your changes you'll have to add or update test files found under `test`.

You can run the full test suite using:

```bash
mix test
```

You can run a single test file using:

```bash
mix test test/just_one_file_test.exs
```

You can run a single test case by adding tags:

```elixir

defmodule SomethingTest do
  @tag focus: true
  test "basic arithmetic" do
    assert 1 + 1 == 2
  end
end
```

Then you can filter based on tag:

```bash
mix test --only focus
```

### How to develop without Elixir installed on your system

It's possible by manipulating the official Docker images
(see: [dockerhub - kitto](https://hub.docker.com/r/zorbash/kitto/),
[Dockerfile](https://github.com/kittoframework/demo/blob/master/Dockerfile)).

We think it's more efficient to have Elixir installed.
Read http://elixir-lang.org/install.html for instructions.

To test Kitto on various Elixir versions we recommend using https://github.com/asdf-vm/asdf-elixir.

## How to develop Kitto - Core JavaScript Library

The core JavaScript Library consists of just 2 files:

* [installer/templates/new/assets/javascripts/application.js][application.js]
* [installer/templates/new/assets/javascripts/widget.js][widget.js]

Until [#39][issue-39] is resolved, the most efficient way to try changes is to experiment from
within a generated dashboard application. When you're happy with your
changes create a pull request for the files above.


## How to develop and test Kitto - Widgets

## Releasing


### How to release a new version of the installer

WIP

* Which files should be included
* How to generate the archive
* Make sure that the archive works
* Place it in the repo (request access for the repo)

### How to release a new version of the Hex package

WIP

* Command to release it
* How to tag it
* How to create the version bump commit

* Upgrading: https://github.com/kittoframework/kitto/wiki/Upgrading-Guide

[hexdocs]: https://hexdocs.pm/kitto/
[kitto-repo]: https://github.com/kittoframework/kitto
[application.js]: https://github.com/kittoframework/kitto/blob/master/installer/templates/new/assets/javascripts/application.js
[widget.js]: https://github.com/kittoframework/kitto/blob/master/installer/templates/new/assets/javascripts/widget.js
[issue-39]: https://github.com/kittoframework/kitto/issues/39#issuecomment-268273382)