Skip to content

Developing Kitto

Jump to bottom
Dimitrios Zorbas edited this page Feb 12, 2017 · 7 revisions 
-> 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.

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/.

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 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:

mix kitto.new kittodev

or clone the demo dashboard:

git clone [email protected]:kittoframework/demo.git

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

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:

mix test

You can run a single test file using:

mix test test/just_one_file_test.exs

You can run a single test case by adding tags:

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

Then you can filter based on tag:

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, 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:

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

[issue-39]: https://github.com/kittoframework/kitto/issues/39#issuecomment-268273382)

Clone this wiki locally