OSDev/Development guide

From Tizen Wiki
Jump to: navigation, search

Purpose of this page

This page shows a typical Tizen developer's daily workflow.

Before you begin

  1. Read the Work Flow first.
  2. Next, read the Quick Start

Roles & Responsibilities

Developers write and submit code to the development (Master) branch of a Git project. There is a refresher on the main GIT branches available, if you need it.

Developers can also review code submissions (push requests) for any project on any branch. To see a current list of open submissions using Gerrit (the code review tool), go to:

[1] -> All -> Open

Development work flow

Note: We recommend reading the distribution workflow page as background for the following information.

Tizen developers use the git and gbs command-line tools for most of their work.

Tizen source code is managed by Gerrit, a code review system for Git-based projects. Source code cloning, development, and review are under ACL (Access Control Lists). Make sure you get rights to access them.

Check out source code

   $ mkdir Tizen_Workingdir
   $ cd Tizen_Workingdir
   $ git clone ssh://<username>@review.tizen.org:29418/<package_name>.git
   /* Note: <username> is the uname of your Tizen account. Make sure your public key is added to gerrit. */

After the git clone is finished, you can make changes and do local commits.

  • Make sure you have pasted your ssh public key into Gerrit.

Make changes

   $ cd <package_name>
   /* do some changes */
   $ git commit -a -m "comments"

You can do several commits at once if you like, but one commit per code review is easier.

Build and test

Before pushing your changes back to Gerrit, build and test to verify the quality of your changes.

Build changes in your home project at OBS

The command below generates a tarball then sends the files from your local Git to the build system and builds them remotely. By default, the target OBS project is home:<user_name>:gbs:Trunk.

   $ gbs build

For a detailed usage guide, see GBS

Build changes in local

You can build your changes in your local environment with this command:

$ gbs localbuild -R http://example1.org/ -A i586

The '-R' option specifies the repository URL the project is built against, '-A' specifies the target architecture, in this case supporting i586 and arm.

For a detailed usage guide, see GBS

Create your own image

To create an image that includes the package you've built locally, see OSDev/MIC

Submit changes to Gerrit for review

Before this step, all your changes have been applied only to your local Git repository. You need to push the changes back to Gerrit for review. Reviewers are notified and review your changes within Gerrit. Push local commits to Gerrit with a command similar to:

$ git push origin HEAD:refs/for/master
  • origin represents the remote.origin.url in .git/config.
  • HEAD is the local commit to be pushed out.
  • refs/for/master is the remote target branch (master) on the Gerrit server. Your changes must be pushed there.

For a detailed Gerrit usage guide, see [2].

How to submit changes to Gerrit

Developer's Submission Checklist

  • 1: Build successfully
    • My package builds successfully against the Tizen repositories (either submitted to OBS home project, or built locally).
    • My package complies with the packaging guidelines.
    • My package does not break other packages.
  • 2: Test
    • I have tested my changes on all relevant hardware. All code must be solid and tested before submission.
    • If I make a change to a big package with a lot of dependents, (such as the kernel, webkit, etc.) I will make sure this does not break any Tizen verticals.
    • If my change causes regressions, I must communicate to Release Engineering what the expected regressions are, and the ETA on when this can be rectified.

Submission auto check policy

The system checks these rules automatically for every patch and submit a score in the Auto Policy Checker category.
Here are the possible scores:

  • "+1" - Passed the auto check.
  • "0" - Passed the auto check, but with warnings.
  • "-1" - Failed the auto check. The changes violate at least one policy.

Gerrit WebUI

The Gerrit WebUI provides features to track the patch review process.

Review a patch set

Note: Only reviewers have the privilege to vote '+2' in the Code Review category, or '+1' in the Verified category.

  • Requirements for a patch set to be accepted

All patches can be reviewed through the web UI and command-line tools. A patch is merged only when:

  • It gets at least one '+2' score and no '-2' scores in the Code Review category; and
  • It gets at least one '+1' score and no '-1' scores in the Verified category; and
  • It gets one privileged user to click the submit button

Note: More than two '+1' doesn't mean '+2'

There are two ways to review a patch set, through the Web UI, or with the command-line tool.

  • Web UI:

Refer to the above section, publish your comments, and vote for the patchset through the Review page.

  • Command-line tool:
   ssh -p <port> <host> gerrit review [--message <MESSAGE>] [--verified <N>] [--code-review <N>] [--abandon]{COMMIT | CHANGEID,PATCHSET}…

Identify a new reviewer

By default, only Project Owners receive notifications when patchsets are uploaded. More reviewers can be invited through the Web UI Main page or specify a reviewer when you push the patch using command-line arguments like this:

   git push --receive-pack='git receive-pack --reviewer=a@a.com --cc=b@o.com'

Watch a project

If you want to receive a notification when a patchset is uploaded to Gerrit, adjust the Watched Projects settings to monitor projects.

Modify an existing patch

Sometimes, developers need to modify an existing patch in Gerrit, according to reviewers' comments. For example, if there is a typo in your patch that you want to fix and resubmit, it is useful to track the patch.

Abandon a patch set

To abandon an uploaded patch, click the Abandon button at Web UI Main Page or use this command:

   $ ssh -p <port> <host> gerrit review [--project <PROJECT>] [--message <MESSAGE>] [--abandon]{COMMIT | CHANGEID,PATCHSET} ...

For detailed instructions, see [3].

Replace a patch set

To add a new patch set that replaces an existing patch set with an updated version of the same logical modifications, send the new commit to the change’s ref number. For example, to add the commit where the SHA-1 starts with c0ffee, as a new patch set for change number 1979, use the push refspec c0ffee:refs/changes/1979:

   $ git push ssh://<USER_ID>@review.tizen.org:29418/<PROJECT_NAME> c0ffee:refs/changes/1979

How to trigger submission to OBS

When submitting changes to Gerrit, a developer might request that a Release Engineer integrate them into a release. For example, Tizen repositories, images, or particularly when the changes include a major upstream release or hot bug fix.

The back-end service helps you submit the changes from Gerrit to OBS only when a commit meets the following criteria:

  • the commit includes only changes in the change log file under packaging directory. Generally, the file name is <PACKAGE_NAME>.changes.
  • a tag is created on this commit, and pushed together with the commit to Gerrit.
  • this commit is accepted and merged on Gerrit after review.

Trigger a submission

These are the steps to trigger a submission:

1. The developer must add a log entry to the top of the change log file to justify their changes. The log entry should be in the format of:

 * Sat Apr 07 2012 User Name <user.name@example.com> - 0.0.1
 - This is an example of log entry, the first line includes date, author name, email and package version number.
 - Every new line should start with '-'.

2. Save the changes to the change log as an individual commit

 git add <PACKAGE_NAME>.changes
 git commit -m 'Version 0.0.1, release to OBS'

3. Create a tag on this commit

 git tag TAG_NAME HEAD 

4. Push the commit and tag together to Gerrit for review.

 git push ssh://<USER_ID>@review.tizen.org:29418/<PROJECT_NAME> HEAD:refs/for/master TAG_NAME

When this commit is accepted and merged on Gerrit, the back-end service commits the change to the build project at OBS, and creates a Submit Request to the production project at OBS.