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. Installation instructions are available in the main Toaster documentation

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.

Workflow

We are now supporting a poky-contrib toaster-next branch. The purpose of this branch is to speed up our work so that we can base patches on top of patches that are waiting for upstream inclusion but have not yet made it into master. To facilitate this we have some extra rebasing actions needed.

To contribute to toaster you will also need authorization to write to the upstream yocto project repository. Contact a member of the toaster team for details.

1) Download master branch of the yocto project

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

2) Add poky-contrib to the local repository you set up above

  git remote add poky-contrib ssh://git@git.yoctoproject.org/poky-contrib 

3) Fetch the poky-contrib branches

  git fetch --all 

4) Start your feature branch off of toaster-next

  git checkout -b the/target/branch poky-contrib/toaster-next 

5) Do Work

6) Rebase on toaster-next. It has probably changed while you were working (unless you are really really fast!)

  git rebase poky-contrib/toaster-next 

7) Send to the toaster-mailing list using one of the methods outlined below.

Sending patches to Toaster Project

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

    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 ( toaster@yoctoproject.org ) by "git send-email".

e.g.

   $ git send-email HEAD^ 

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 into Bitbake

All Toaster patches need to be submitted upstream to the Bitbake repository after they have been reviewed on the Toaster mailing list. Since development happens on the poky-contrib repository, but the patches need to be merged to the Bitbake repository, the following process should be executed.

1) Bring toaster-next up to date with master

  git fetch poky-contrib toaster-next&& git fetch origin master
  git checkout -b toaster-next poky-contrib/toaster-next 
  git rebase origin/master 

2) Checkout the target branch

  git checkout the/target/branch

3) Create a new branch for submission

   git checkout -b yourname/submit/the/target/branch 

4) Make sure the branch is rebased on current poky-contrib toaster-next.

  git rebase poky-contrib/toaster-next

5) Test the changes. Run the Django unit tests. People put effort into these so we should make sure we use them.

 bitbake/lib/toaster/manage.py test orm toastergui

6) Add signed off by to the commit messages

  git filter-branch -f --msg-filter 'cat && echo "Signed-off-by: $(git config --get user.name) <$(git config --get user.email)>"' toaster-next..HEAD

7) Push the modified commit messages and rebased version to poky-contrib

  git push -u poky-contrib yourname/submit/the/target/branch 

8) Use the create-pull-request script (from poky) to create a pull request

  ./scripts/create-pull-request -d bitbake -s "toaster: Fixes and clean ups" -u poky-contrib -r poky-contrib/toaster-next

9) Review their content, especially the summary mail:

  edit ./pull-<pid>/0000-cover-letter.patch

10) Push the branch you just signed off on and sent upstream to toaster-next

  git push -f -u  poky-contrib yourname/submit/the/target/branch:toaster-next 

When you are satisfied, you can send them with:

  ./scripts/send-pull-request -a -p ./pull-<pid> -t bitbake-devel@lists.openembedded.org

Submitting patches for prior releases

The procedure is the same, but using the prior release as the base branch instead of the "master" branch in bitbake.

Also, make sure that you add the name of the prior release for which the patchset is intended in the prefix of the patchset, as parameter to the "create-pull-request" command, e.g. -p 1.26 for the 1.26 branch.

Gotchas

Sometimes the mailer will refuse to send patches, especially on binary or long-line files. The proper way to go around that is to reply to the patchset you've submitted to the mailing list, asking for a git pull directly from the poky-contrib branch.
The toasterconf.json files live in the meta and meta-yocto layer. Patches to the meta-yocto/conf/toasterconf.json go to poky@yoctoproject.org. Patches to meta/conf/toasterjson.conf go to openembedded-core@lists.openembedded.org.

Submitting patches for documentation

Documentation patches should be sent to Yocto mailing list with [yocto-docs] in the subject, CC Scott Rifenbark (and make sure you send it to his gmail, not his defunct Intel address). For his email address, look at this post.

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 --load-plugins pylint_django toastergui/tests.py

Working with design

Yes, the Yocto Project is one of those lucky projects with designers around to help in UI matters. We have a document explaining how to work with the design contributors: File:Working with design.pdf