Contribute to Toaster

This page summarises the Toaster development process. We hope this will help you start contributing to the project.

What can I do?

The Yocto Project Bugzilla instance lists all the things that need to be done:

• If the issue says GUI design available in the Whiteboard field, there is a design specification document attached to the issue that you should follow. Send questions / comments about it to the Toaster mailing list
• If the issue says GUI design pending in the Whiteboard field, there is some design work still to be done. Feel free to take the issue and send an email to the Toaster mailing list to find out why the design work is not done yet

Set up the local repository

For development of Toaster we recommend setting up a local install of Toaster. General install instructions are available in the main Toaster documentation

Clone the poky repository

   $ git clone git://git.yoctoproject.org/poky
   $ cd poky

Install a python virtual environment to sandbox the python modules from your OS. Enter Activate the python virtual environment in your current shell.

   $ virtualenv venv
   $ source ./venv/bin/activate

Install the python module dependencies for Toaster

   $ pip install -r ./bitbake/toaster-requirements.txt

Run the setup and start script, follow instructions displayed

    $ TOASTER_MANAGED=1 TOASTER_DEVEL=1 ./bitbake/bin/toaster

Submitting patches

Publishing your patches to Toaster is a two step process.

1. Sending patches to Toaster Project for review
2. Submitting the patches that you reviewed to the upstream repository

Toaster code lives in Bitbake repository at [1]. All contributions must be upstreamed to the Bitbake repository in order to make it to the "master" branch of the poky/ repository.

Sending patches to Toaster Project

NOTE: The format of the commit message should be like this

    bitbake: toaster: <short one line summary>

    long(er) description

    [YOCTO #0000]

    Signed-off-by: First Last <name@domain.com>

Where YOCTO #0000 is the related bug number if there is one. Signed off by with your git commit -s credentials.

We accept patches on the toaster mailing list by "git send-email" please include in your subject line "[review-request][PATCH]"

e.g.

   $ git send-email HEAD^  --subject-prefix="review-request][PATCH" 

A comprehensive document about commit messages is available on the openembedded wiki

More help learning git is available on github and the official documentation

Sending branches to Toaster Project

If you wish to submit whole branches please use the poky-contrib repository see Poky Contributions#Poky_Contrib_Branch for setup guide.

Once you have pushed a branch please then send an email to the toaster mailing list with the subject in the following format:

[review-request] my_branch_name

In the body of the email it's useful to describe your branch's functionality, which commits and a link to the git web.

If you need any assistance please post on the mailing list.

Submitting patch sets for integration upstream

All Toaster patches need to be submitted upstream to the Bitbake repository. Since development happens on the poky repository, but the patches need to be merged to the Bitbake repository, the following process should be executed.

• You will need a bitbake/ checkout separated from your current poky/ checkout. You can use one at the same level, e.g. ~/poky/ and ~/bitbake/ are your checkout directories.
• Make sure you have a clean directory which you can use to store the patches during the transition from poky/ to bitbake/. e.g. ~/patches
• Let's assume you are on the "ownname/work_branch" branch in the poky/ tree at the and on the "master" branch in the bitbake/ tree

1. Make sure that the ~/patches directory exists and it is clean

mkdir -p ~/patches && rm -f ~/patches/*

1. Export the toaster patches from the "ownname/work_branch" bitbake directory to the patches/ directory

cd ~/poky/bitbake && git format-patch -o ~/patches/ --relative 

1. Create a submission branch in the bitbake/ git checkout and import the patches exported from poky/; NOTE: Make sure that the patchset is rebased on top of the latest master branch.

cd ~/bitbake/ && git checkout origin/master -b submission && git pull
find ~/patches/ -type f -name *patch | sort -n | xargs -n1 git am

1. Now we need to review this branch. All patches must be signed-off as reviewed by the upstreamer, which cannot be author of the patch.

git rebase -i origin/master

1. and edit each patch in part (s/^pick/edit/) to add your signature

git log -n1 -p
# if ok
git commit --amend -s
git rebase --continue

1. push the submission patch to poky-contrib (yes, the bitbake/ tree can be pushed as branch to the poky-contrib repo

git push poky-contrib submission:ownname/bitbake_submission

1. and use the "create-pull-request" and "send-pull-request" from the poky/ repository in the poky/scripts/ directory to create a pull request and submit it to bitbake-devel@lists.openembedded.org; yes, you use the poky scripts in the bitbake/ directory

~/poky/scripts/create-pull-request -u poky-contrib -b ownname/bitbake_submission

1. edit the patchset message in the pull-XXXX/0000-*.patch

~/poky/scripts/send-pull-request pull-XXXX/

Code syle guide

Templates

Django has a template language which allows us to render pages based on the data (context). We use the template language to setup the initial state of the page and to create re-usable components that can be included in other pages.

The recommend template code style is as follows

Yes please:

{{var}}

<div>
  {# Maintaining indentation #}
  {% if %}
   <p>this</p>
  {% else %}
   <p>that</p>
  {% endif %}
</div>

{% comment %}
This is a longer comment that describes all the things
that are below in quite a bit of detail because they're
a little more difficult to understand.
{% endcomment %}

{% for layer in layers_list %}
 {{layer}}
{% endfor %}

No thank you:

{{var}}
<div>
{# Maintaining indentation #}
{%if%}<p>this</p>{%else%}<p>that</p>{%endif%}
</div>


{#This is a longer comment that describes all the things that are below in quite a bit of detail because they're a little more difficult to understand. #}
{%for o in layers_list%}{{o}}{%endfor%}

Note:

• Maintain indentation as you would with other languages
• White space after '%'
• Comment blocks for longer comments

Javascript

Yes please:

"use strict";

/* These hold some numbers */
var oneVar = 1;
var twoVar = 2;

var cheesesTypes = {
  cheddar : 1,
  stilton : 2,
  emmental : 3, 
};

function doThingsHere(){
  return 1;
}

/* If one equals two do some other things and make sure that
 * if the the click handler is setup correctly.
 */
if (one === two) {
  var cheese = "cheddar";
  oneVar = doThingsHere();

  $(this).click(function (event){
    alert("Hello");
  });
}

$("#little-mouse").focusout(function(){
  alert("bye")
});

if (oneVar)
  noThingHere();
else
  doThingHere();

No thank you:

// These hold some numbers
oneVar = 1
twoVar = 2

var cheesesTypes = { cheddar : 1, stilton : 2,  emmental : 3, }

function doThingsHere ()
{
return 1;
}

//If one equals two do some other things and make sure that if the the click handler is setup correctly.
if( one === two ) {
var cheese = "cheddar";
oneVar = doThingsHere();

    $(this).click(function(event){ alert("Hello"); });
}

document.getElementById("little-mouse").addEventListener("focusout", function(){
  alert("bye")
});

if (oneVar)
{
  noThingHere();
} else {  doThingHere(); }

Note:

• Variables should be marked with "var"
• Semicolons should be used
• Keep as close to 80 cols as possible
• Use 2 space per indentation
• Open curly braces after parenthesis for functions and close on a new line
• Use camelCase for function names and variable names

Make use of running your Javascript through jshint we have a .jshint configuration file in that js directory (toastergui/static/js)

e.g. install jshint and add to your current PATH, then run:

$ npm install jshint; export PATH=$PATH:$PWD/node_modules/.bin/
$ jshint ./toastergui/static/js/base.js

HTML

Yes please:

<div id="something-area">
  <p class="important">This is some text</p>
</div>

<div>
  <p id="important-text>This is some text</p>
</div>

No thank you:

<div id="somethingarea">
    <p class="Important">This is some text</p></div>
<div id="somethingarea">
<p id="ImportantText">This is
some text
</p>

</div>

Note:

• 2 space indentation
• Lower case, ids hyphenated when multiple words
• No duplicate ids

• Run your HTML through a HTML validator available for local install. The w3c validator it's self doesn't currently validate html5, it uses as a back end Nu Html Checker which can be installed as a standalone service, full instructions in the readme.

Quick install instructions:

 $ mkdir html5-validator && cd html5-validator
 $ export JAVA_HOME=/usr/lib/jvm/java-6-openjdk
 $ git clone https://github.com/validator/validator.git
 $ python build/build.py all
 $ python build/build.py all

HTML can be indented quickly using tidy, for example:

 tidy -xml --indent auto --indent-spaces 2 --quiet yes -w -1 --show-body-only yes  ./index.html 

Python

Lenient pep8 Ignoring most of the whitespace around character issues (E124,E203,E201,E265,E303,E302,E231) see toaster/.pep8 and error code list

Fix all issues identified by running code through pep8. We have a fairly lenient config file (toaster/.pep8).

e.g.

$ pep8 ./toastergui/urls.py

Run code through pylint and fix identified issues - Some can be reasonably ignored such as doc strings for every function or star-args. No pylintrc config provided here as most issues identified are highly contextual and should be ignored on a case by case basis.

$ pylint ./toastergui/views.py