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

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

Make use of jQuery http://api.jquery.com
Variables should be marked with "var"
Semicolons should be used
Keep as close to 80 cols as possible
Use proper indentation
Curly brackets after parenthesis
Lots of common functions can be found in libtoaster.js
Use camelCase for function names and variable names

Python

Roughly follows pep8 https://www.python.org/dev/peps/pep-0008/

Contribute to Toaster

Contents

What can I do?

Set up the local repository

Set up the project and Toaster interface

Prepare your SSH credentials for pushing to Yocto Project

Edit and submit content for review

Rebase your repository from toaster/master

Style guide DRAFT

Templates

Javascript

Python

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools