Skip to content

Developing Kitto

Jump to bottom
Dimitrios Zorbas edited this page Feb 17, 2017 · 7 revisions

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

We divide widgets in 2 categories, core and custom.

You can browse a list of all available core widgets [here][core-widgets].

Core Widgets

They are intended to offer basic functionality for common tasks like displaying a simple meter or some text.

Their source code is placed under the widgets directory upon the creation of a new dashboard application using mix kitto.new <dashboard-name>.

To develop a new core widget you should implement it inside an existing dashboard application and then create a pull request to add it in installer/templates/new/widgets/new-core-widget. You should write documentation to be added in the available [core widgets][core-widgets] wiki for the widget.

How to release a new version of the installer

The installer handles the creation of a new dashboard by exposing the following mix task:

mix kitto.new <dashboard-name>

For the installer to be available, a user has to install the installer Mix archive.

Create the archive

From the kitto repository:

cd installer
MIX_ENV=prod mix archive.build

This will create a file kitto_new-X.Y.Z.ez where X.Z.Y is the version number.

Release the archive

All releases are kept in the [archives repository][archives-repo]. You can request for access to the repository at [gitter][gitter].

You should add the new archive to the archives repo and commit with a message like [this one][archives-commit], keeping in mind to update the readme to point to the latest archive.

You should make sure that the archive works and is installable using:

mix archive.install https://github.com/kittoframework/archives/raw/master/kitto_new-X.Y.Z.ez

How to release a new version of the Hex package

To release a new version of the [Hex package][kitto-hex], follow these steps:

  1. Make sure the tests are passing
  2. Create a release commit like [this one][release-commit]

The commit should contain changes to the following files:

mix.exs: The version of the project is updated
installer/mix.exs: The version of the installer is updated

The version to the installer is bumped to match the one of the Hex package, even when the installer hasn't changed.

CHANGELOG.md: An entry for the new version has to be added
README.md: The installer archive installation command has to be updated

  1. Document any introduced incompatibilities in the [upgrade guide][upgrade-guide]
  2. Push the package
mix hex.publish

[issue-39]: https://github.com/kittoframework/kitto/issues/39#issuecomment-268273382) [core-widgets]: https://github.com/kittoframework/kitto/wiki/Available-Widgets [archives-repo]: https://github.com/kittoframework/archives [gitter]: https://gitter.im/kittoframework/Lobby [archives-commit]: https://github.com/kittoframework/archives/commit/f56502523e0c1d9b274b8e96bcd0d0ab8e4bee02 [kitto-hex]: https://hex.pm/packages/kitto [release-commit]: https://github.com/kittoframework/kitto/commit/1b245f57726c98ac8fa0e3b6e308ff229aafc544 [upgrade-guide]: https://github.com/kittoframework/kitto/wiki/Upgrading-Guide

Clone this wiki locally