Ubuntu Touch Core Apps Project:
Before You 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 Alan Pope 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.
Here is how you get started. If you have any questions, feel free to email Alan Pope
Join The Mailing List
You should first join the ubuntu-touch-coreapps mailing list. To do this, head over to https://launchpad.net/~ubuntu-touch-coreapps/+join and join the open team. You can see the list archives at https://lists.launchpad.net/ubuntu-touch-coreapps/
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
Following Coding Conventions
The code developed Core Apps developers and potential contributors should be high in quality. In order to ensure the code being developed is readable and easy to understand and fix for future developers, it is recommended that developers read and follow the principles in the QML Coding Conventions page.
Following this guide ensures that future developers in your shoes are happy with the code they are working with--you would appreciate someone doing the same for you, right?
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>
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:
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.
Ubuntu Phone Core App Development Principles
In developing the Ubuntu Phone Core Applications we will be using a declarative approach for creating the user experience. The Ubuntu SDK includes QtQuick2 for this purpose, and we will be creating our applications in a way that maximizes our use of this amazing technology.
If you are familiar with QtQuick in general already, and especially QtQuick2, then you might still find this short guide useful in describing the principles we would like to adhere to during development.
Please note we do not support QtQuick1, so to keep things simple, when you read QtQuick in the remainder of this document it will be referring to QtQuick2. You may notice that the terms will be used interchangeably.
So to summarize the principles:
- When defining your user interface it will be done in QML
- When all else fails or the above simply is not appropriate then improve the C++ that controls the declarative engine
coordinate features in meetings and on the list
Use Blueprints to Track Work
find the bugs list
assign the bug to you
fix the bug and submit as a merge proposal
Additionally, there are Python standards used and enforced by the Continuous Integration testing framework used by the various projects. There are times when otherwise small updates to the tests can trigger Python coding standard violations. These are known as PEP8 failures. More information about fixing such issues can be found in the PEP8 Style Guide. In order to verify any fixes to the Python code to ensure such violations have been fixed, run the 'pep8' program from the command line against any offending source files. PEP8 can be installed by doing a "sudo apt-get install pep8".
Another error checking program that is ran against source files is Pyflakes. If Continuous Integration finds a Pyflakes violation, any updated Python source files can be checked using the 'pyflakes' program which can be installed by doing a "sudo apt-get install pyflakes".
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.
For the Project Team
If you are a member of a Core Apps development team, you have the added responsibility of ensuring that merge proposals to your project are reviewed in a timely, friendly manner.
Viewing Merge Proposals
To see pending merge proposals, go to the code section of your project's Launchpad page, and click the active reviews link
From there you can see the list of pending reviews and their status. Pick one that is available for you to review, and you will be taken to a page with a description of the changes being made, and the visual diff between it and the target branch (usually trunk).
Reviewing a Merge Proposal
In order to perform a review, first read through the visual diff on the merge proposal page. If you have any questions or concerns at this point, leave a comment for the contributor with a review type of Comment Only, Needs Information or Needs Fixing. If a review of the diff looks good, try merging the branch into a clean, local copy of the target branch (usually trunk) by doing the following:
bzr merge <proposed_branch>
Then try running the app. If you encounter any problems, provide as much detail about how to reproduce it as you can in the merge proposal page, and set the review to Needs Fixing.
If everything merges cleanly, runs properly, and you are happy with the contribution, leave a comment to that affect with a review type of Approved, then set the merge proposal's status to Approved as well.
A big part of maintaining a project in Launchpad is making sure that you are looking after any bugs reported by your users. When a user reports a bug, they will provide as much detail as they can, but then it's up to the project team to properly tag them, define their importance, and keep their status up to date.
You should make a habit of regularly (once a week or more) looking at new bug reports. First make sure they are valid for your project, and if not try to re-assign them to a more appropriate one. Second, see if the user has provided enough information for you or another developer to fully understand the problem, and if not ask the reporter for any specific details that would help. If you know where in the code the problem might originate, or how it might be fixed, leave a comment to that affect for whichever developer might end up fixing it. Finally, assign an importance to the bug, from Wishlist all the way up to Critical, to help you prioritize the work.
You can learn more about how to effectively triage bugs here: Bugs/HowToTriage