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:

• See a full list of Toaster issues

• See a list of Toaster user interface issues
  • 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

We have some sample data for development purposes you can download: File:Toaster.sqlite. Save the file to your /poky/build/ directory.

Set up the local repository

• Select a Yocto Project 1.5 compatible host, install Django-1.5 and South 0.8.4. The "pip" application is recommended to manage the install process.

   $ sudo apt-get install pip
   $ sudo pip uninstall django
   $ sudo pip install django==1.5
   $ sudo pip install South==0.8.4

• Here is an example alternate method for installing "pip" if the above method does not work with your host.

   $ curl --silent --show-error --retry 5 https://raw.github.com/pypa/pip/master/contrib/get-pip.py | sudo python2.7

• Setup a local repository for the development branch, and setup up your branch for pushes to the Yocto Project poky-contrib repository

   $ cd <installdir>
   $ git clone git://git.yoctoproject.org/poky
   $ cd poky
   $ git remote set-url origin git://git.yoctoproject.org/poky
   $ git remote add poky-contrib ssh://git@git.yoctoproject.org/poky-contrib
   $ git fetch --all -p

Set up the project and Toaster interface

• Run a build, with Toaster database capture enabled

   $ cd <installdir>
   $ source poky/oe-init-build-env
   $ source toaster start
   $ bitbake core-image-minimal

NOTE: Toaster MUST be started before you start your build, else no data will be captured. You can recover a working (if sparse) database if you do this to execute a quick re-build.

   $ source toaster start
   $ bitbake -c cleansstate base-files
   $ bitbake core-image-minimal

• Run the Toaster interface

   $ xdg-open http://localhost:8000/

NOTE: You can alternatively open your browser manually and point it to http://localhost:8000/

Prepare your SSH credentials for pushing to Yocto Project

• Insure that you have registered your <username> with Yocto Project to enable you to push content. You can choose any user name (for example "dreyna") and send it to Michael Halstead (mhalstead at linuxfoundation dot org), together with your SSL public key to enable your pushes to the Yocto Project poky-contrib repository.

• You can run the following command to create the ssh key, noting that you just want to hit return after any of the questions the shell script asks, including the password questions. You will then send the resulting "~/.ssh/id_*.pub" files as your public keys.

   $ ssh-keygen -t dsa

Edit and submit content for review

• Create a local branch. The BRANCH_NAME is generally of the form <username>/<a_name_for_the_branch> (for example: dreyna/recipe-detail-view), using:

   $ git checkout origin/master -b <BRANCH_NAME>

• Edit and test your content. You might find Firebug useful for web development purposes. If you need some sample data to test your code, download File:Toaster.sqlite

• Validate your code.
  • Make sure that all files are in Unix format (and not say DOS by accident)
  • Fix any white space at the end of line; i.e, there should not be white space on any line before \n; $ sed -i "s/space:\+$//" <file>
  • Validate your markup for HTML format compliance. There are lots of HTML validators you can use: HtmlValidator is one of them.

• Set up your commit(s). The same push can have several partitioned commits. First, add the content for the commit:

   $ cd <installdir>/poky
   $ git add [-p] bitbake/lib/toaster/...

The -p patch interactive option can help you preview the changes.

Then, create the commit:

   $ git commit -s

The -s option adds the Signed-off-by to your patches.

NOTE: The format of the commit should be like this

   vvvvvvvvvvvvvvvvvvvvvvvvv
   bitbake: toaster: <short one line summary>
   

   <long(er) description, can be multi-line, should break at around 60 chars>
   

   [YOCTO #0000]          # replace with the bugzilla issue number; there can be multiple lines 
   

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

If your patch is directly addressing a Bugzilla issue, you should reference the issue number by adding the YOCTO #0000 line just above the Signed-off line.

A comprehensive document about commit messages is available at:

http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines

• Push your branch for review. You may need -f if this is a commit update, which should be fine since the push is to a private branch managed only by you. The argument to rebase is a ref (branch name, tag name, hash, etc.).

   $ git push [-f] poky-contrib <BRANCH_NAME>

See it on the web using the branch name. For example:

http://git.yoctoproject.org/cgit/cgit.cgi/poky-contrib/?h=dreyna%2Frecipe-detail-view

• Send an email to the Toaster mailing list with the following content:
  • Preface the email's subject line with "[review-request]", so that it be routed correctly in each reviewer's mail box
  • A brief description of the review request together with the branch name
  • Any technical details to call out to reviewers
  • Any limitations, assumptions, dependencies, and/or differed work
  • Ideally, a test plan that demonstrates how the feature was tested with sufficient detail for general testers and documentation writers. This is a test plan example you can use as a reference.

NOTE: Once your receive a reply on the mailing list confirming that the patches are merged, abandon the branch and start new development on a new branch. To delete an old branch, proceed the branch name with a ":".

   $ git push poky-contrib :<OLD_BRANCH_NAME>

• Update the Bugzilla entry. If your patch is directly addressing a Bugzilla issue, please mark the Bugzilla entry as "In Progress Review", and when the patch is merged into upstream bitbake/master (not poky-contrib/toaster/master), please mark the Bugzilla entry as "Resolved / Fixed". This will let the QA team know what happens to the code base and the Bugzilla entries.

Rebase your repository from toaster/master

To update your repository to the latest content, rebase it (as opposed to attempting a merge, which can lose history).

   $ cd <installdir>/poky
   $ git fetch
   $ git rebase [-i] origin/master

Style guide DRAFT

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(); }

• 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 and add to your current PATH, then run:

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

Python

Lenient pep8 (https://www.python.org/dev/peps/pep-0008/) Ignoring most of the whitespace around character issues (E124,E203,E201,E265,E303,E302,E231) see toaster/.pep8 http://pep8.readthedocs.org/en/latest/intro.html#error-codes

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