DevelopmentGuide

Differences between revisions 1 and 13 (spanning 12 versions)
Revision 1 as of 2013-01-29 17:19:25
Size: 2016
Editor: jonobacon
Comment:
Revision 13 as of 2013-02-07 15:30:24
Size: 6561
Editor: dpm
Comment:
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:
 * Download and install the SDK from http://developer.ubuntu.com - you should also run through the tutorial to get acquainted with the technology.
 * Sign the Contributor Agreement - email kevin.wright@canonial.com for details - we need to ask folks to sign this as many carriers and handset manufacturers require specific license agreements, and this allows us to dual-license the code between both a a fully Free Software license and a license that might be required for a handset manufacturer or operator.
 * Download and install the SDK from [[http://developer.ubuntu.com/gomobile|the Ubuntu App Developer Site]] - you should also run through the tutorial to get acquainted with the technology.
 * Sign the [[https://forms.canonical.com/contributor|Contributor Agreement]] - email [[LaunchpadHome:kevin-wright-1|Kevin Wright]] for details - we need to ask folks to sign this as many carriers and handset manufacturers require specific license agreements, and this allows us to dual-license the code between both a a fully Free Software license and a license that might be required for a handset manufacturer or operator.
Line 14: Line 14:
Here is how you get started. If you have any questions, feel free to email kevin.wright@canonical.com. Here is how you get started. If you have any questions, feel free to email [[LaunchpadHome:kevin-wright-1|Kevin Wright]]
Line 16: Line 16:
== Join The Mailing List == === Join The Mailing List ===
Line 18: Line 18:
You should first join the `ubuntu-phone` mailing list. To do this, head over to https://launchpad.net/~ubuntu-phone and join the list. You can see the list archives at https://lists.launchpad.net/ubuntu-phone/ You should first join the `ubuntu-phone` mailing list. To do this, head over to https://launchpad.net/~ubuntu-phone/+join and join the open team. You can see the list archives at https://lists.launchpad.net/ubuntu-phone/
Line 23: Line 23:
[ubuntu-calendar-app] My subject title [Calendar] My subject title
Line 28: Line 28:
== Getting The Code == === Getting The Code ===
Line 30: Line 30:
To get the code, go to the wiki page for the app you are interested in and click the ''Code'' link. You can then see how to branch the code. To get the code, go to the wiki page for the app you are interested in and click the ''Launchpad Project'' link. You can then see how to branch the code.
Line 38: Line 38:
== Coordinating What To Work On == === Using Bzr ===

Bzr is the primary version control system used by Ubuntu and Ubuntu projects. Bzr is quite like other distributed version control systems, just as Git and Mercurial in that you have both a local checkout '''and''' the full branch history locally. This allows you to branch, commit and merge code without being connected to a central server.

When you branch the project's code (using the command above), you get the full history of the branch, with the tip (HEAD) checked out in your new directory. When you make changes to this code you will need to commit is to your branch history by running:

{{{
bzr commit -m "Commit Message"
}}}

This commits your changes to your local branch history, but not to the remove Bzr branch that you pulled from. You can commit as much as you like to this local branch history until you are ready to submit all of your changes back to the original branch.

When you are ready to submit your changes, you will need to push them back to Launchpad. You should not push to the same branch you pulled from however, instead you should push to a new branch location where you changes can be reviewed before making it way to trunk. Do do this, run the following command:

{{{
bzr push lp:~<your_launchpad_username>/ubuntu-calendar-app/<unique_branch_name>
}}}

You'll need to have a launchpad profile, and give your branch a unique name that you can use to identify it. Replace '''ubuntu-calendar-app''' with the name of the project you are working on. You can then open the new branch in your browser with:

{{{
bzr launchpad-open lp:~<your_launchpad_username>/ubuntu-calendar-app/<unique_branch_name>
}}}

=== Using Launchpad ===

Once your code is in Launchpad, you need create a Merge Proposal to submit it back to the trunk branch. When you open your branch in the browser, you will see the following link:

{{attachment:propose_for_merging.png}}

On the next page you will provide a description of your changes to help the reviewer understand what they are looking at or looking for. The more information you provide here, the easier it will be for the reviewer. If your merge proposal needs more work, the reviewer will leave you comments on the new merge proposal's page. If it is accepted, your branch will be merged into the project's trunk, there is nothing more you need to do.

You can continue to commit code to your local branch, and your merge proposal will be updated when you run '''bzr push''' again to the same location. You should limit what you push to this branch to only what is necessary for the fix or feature you are implementing. If you want to work on some other aspect of the project, you should create a new local branch and push to a new remote location.


== For Developers ==
Line 43: Line 78:
Line 44: Line 80:
Line 49: Line 86:
Line 50: Line 88:
Line 52: Line 91:
== Reviewing Branches == === Talking about your work ===

While you are working on one of these Core Apps, it's always nice to show off your progress and get input from the wider community. Posting screenshots or, better still, screencasts will let non-developers and future users see what is being done. Raising excitement around your contributions is also a great way to get more people involved in making them.

If you have a personal blog, you can use it to chronicle your Core Apps contributions, solicit feedback and comments, and generally make people aware of what you are doing. If you are an [[Membership|Ubuntu Member]] you can also have these posts syndicated to the [[http://planet.ubuntu.com|Ubuntu Planet]] for even more exposure. Using a specific tag (in Wordpress, for example) will also allow people to easily find all of your related posts.

You are also encouraged to use the Ubuntu Phone Mailing List (mentioned above) to talk about major features or milestones, ask for design input, or to seek advice on how best to implement something. Not only will you be able to receive help from the mailing list, but you will also show how active the development is.

Finally, you can use the existing Ubuntu communities on [[http://www.reddit.com/r/Ubuntu/|Reddit]] and [[https://plus.google.com/u/0/communities/111350780270925540549|Google+]] to show people your app or feature and get it noticed.

== For the Project Team ==

=== Workflow Overview ===

{{attachment:Development+workflow.png|Development workflow diagram|width=850}}

=== Reviewing Branches ===
Line 56: Line 111:
== Contributing Your Branch == === Triaging Bugs ===
Line 58: Line 113:
how to upload the branch to LP and then submit a merge proposal how to manage bug reports and get them ready for developers

=== Promoting the project ===

How to publicly promote the project, plans and progress

Development Guide

Before Your Start

There are a few things you should do before you start hacking:

  • Download and install the SDK from the Ubuntu App Developer Site - you should also run through the tutorial to get acquainted with the technology.

  • Sign the Contributor Agreement - email Kevin Wright for details - we need to ask folks to sign this as many carriers and handset manufacturers require specific license agreements, and this allows us to dual-license the code between both a a fully Free Software license and a license that might be required for a handset manufacturer or operator.

Getting Started

Here is how you get started. If you have any questions, feel free to email Kevin Wright

Join The Mailing List

You should first join the ubuntu-phone mailing list. To do this, head over to https://launchpad.net/~ubuntu-phone/+join and join the open team. You can see the list archives at https://lists.launchpad.net/ubuntu-phone/

When sending emails to the list, please put app name from the Launchpad project in square brackets in your subject line. As an example, for the Calendar app:

[Calendar] My subject title

This helps us to filter the list better.

Getting The Code

To get the code, go to the wiki page for the app you are interested in and click the Launchpad Project link. You can then see how to branch the code.

For example, for the calendar you run:

bzr branch lp:ubuntu-calendar-app 

Using Bzr

Bzr is the primary version control system used by Ubuntu and Ubuntu projects. Bzr is quite like other distributed version control systems, just as Git and Mercurial in that you have both a local checkout and the full branch history locally. This allows you to branch, commit and merge code without being connected to a central server.

When you branch the project's code (using the command above), you get the full history of the branch, with the tip (HEAD) checked out in your new directory. When you make changes to this code you will need to commit is to your branch history by running:

bzr commit -m "Commit Message"

This commits your changes to your local branch history, but not to the remove Bzr branch that you pulled from. You can commit as much as you like to this local branch history until you are ready to submit all of your changes back to the original branch.

When you are ready to submit your changes, you will need to push them back to Launchpad. You should not push to the same branch you pulled from however, instead you should push to a new branch location where you changes can be reviewed before making it way to trunk. Do do this, run the following command:

bzr push lp:~<your_launchpad_username>/ubuntu-calendar-app/<unique_branch_name>

You'll need to have a launchpad profile, and give your branch a unique name that you can use to identify it. Replace ubuntu-calendar-app with the name of the project you are working on. You can then open the new branch in your browser with:

bzr launchpad-open lp:~<your_launchpad_username>/ubuntu-calendar-app/<unique_branch_name>

Using Launchpad

Once your code is in Launchpad, you need create a Merge Proposal to submit it back to the trunk branch. When you open your branch in the browser, you will see the following link:

propose_for_merging.png

On the next page you will provide a description of your changes to help the reviewer understand what they are looking at or looking for. The more information you provide here, the easier it will be for the reviewer. If your merge proposal needs more work, the reviewer will leave you comments on the new merge proposal's page. If it is accepted, your branch will be merged into the project's trunk, there is nothing more you need to do.

You can continue to commit code to your local branch, and your merge proposal will be updated when you run bzr push again to the same location. You should limit what you push to this branch to only what is necessary for the fix or feature you are implementing. If you want to work on some other aspect of the project, you should create a new local branch and push to a new remote location.

For Developers

Feature Development

join meetings

coordinate features in meetings and on the list

use blueprints to track this work

Fixing Bugs

find the bugs list

assign the bug to you

fix the bug and submit as a merge proposal

Talking about your work

While you are working on one of these Core Apps, it's always nice to show off your progress and get input from the wider community. Posting screenshots or, better still, screencasts will let non-developers and future users see what is being done. Raising excitement around your contributions is also a great way to get more people involved in making them.

If you have a personal blog, you can use it to chronicle your Core Apps contributions, solicit feedback and comments, and generally make people aware of what you are doing. If you are an Ubuntu Member you can also have these posts syndicated to the Ubuntu Planet for even more exposure. Using a specific tag (in Wordpress, for example) will also allow people to easily find all of your related posts.

You are also encouraged to use the Ubuntu Phone Mailing List (mentioned above) to talk about major features or milestones, ask for design input, or to seek advice on how best to implement something. Not only will you be able to receive help from the mailing list, but you will also show how active the development is.

Finally, you can use the existing Ubuntu communities on Reddit and Google+ to show people your app or feature and get it noticed.

For the Project Team

Workflow Overview

Development workflow diagram

Reviewing Branches

how to review someone elses branch

Triaging Bugs

how to manage bug reports and get them ready for developers

Promoting the project

How to publicly promote the project, plans and progress

Touch/CoreApps/DevelopmentGuide (last edited 2014-06-05 12:10:08 by popey)