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 has all the stuff that needs to be worked on:

• 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
  • If they 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 contact Belén (belen dot barros dot pena at intel dot com) to find out why is the design work not done yet.

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

• Setup a local repository for the development branch

   $ cd <installdir>
   $ git clone git://git.yoctoproject.org/poky
   $ cd poky
   $ git remote add contrib http://git.yoctoproject.org/git/poky-contrib
   $ git fetch contrib
   $ git checkout contrib/toaster/master -b toaster-master

• Setup up your branch for pushes to the Yocto Project poky-contrib repository

   $ git remote set-url contrib git@git.yoctoproject.org:poky-contrib

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/

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. You can choose any user name 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. For example:

   $ git checkout -b dreyna/recipe-detail-view

• Edit and test your content. You might find Firebug useful for web development purposes.

• 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]          # OPTIONAL LINE: replace with the real bugzilla issue number 
   

   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] contrib dreyna/recipe-detail-view

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:
  • 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.

• 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] contrib/toaster/master