Contribute to Toaster

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

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 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. All rendered pages should be validated 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.

   $ cd <installdir>/poky
   $ git add bitbake/lib/toaster/...
   $ git commit -s

Use $ git commit -s so that you don't need to add the Signed-off-by manually to your patches.

You might also find $ git add -p [filename] helpful. It will allow you to review multiple changes to a single file one by one.

NOTE: The format of the commit should be like this

   vvvvvvvvvvvvvvvvvvvvvvvvv
   <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

• Rebase your branch on the latest toaster/master. This will lower the probability that your code will conflict when trying to merge the patch upstream by making sure it's based on the latest upstream.

• Push your branch for review. For example, if you branch name is dreyna/recipe-detail-view:

   $ git push poky-contrib dreyna/recipe-detail-view

• Send an email to the Toaster mailing list with the following content:

• Once the email comes back that the patches are merged, please abandon the branch, and start new development on a new branch.

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

• 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 know what happens to the code base and the Bugzilla entries.

Rebase your repository from master

To update your repository to the latest content, rebase it (as opposed to attempted a merge).

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