Merge lp:~emailgirishrawat/ubuntu-calendar-app/READMEs into lp:ubuntu-calendar-app

[Girish]

Expanded and updated READMEs.

Expanded and updated READMEs.

Added:
* README.autopilot
* README.developers
* README.mergeproposal
* README.unittest

Modified:
* README
* README.translations

[Dan Chapman  (dpniel)]

Looks good. Just a few issues for which I've left comments inline.

review: Needs Fixing

[Dan Chapman  (dpniel)]

See comments in line

[Girish (emailgirishrawat)]

So should I remove "Note: As of vivid 15.04, the autopilot tests are broken in trunk As such autopilot failures can be excused until they are fixed."?

[Girish (emailgirishrawat)]

Fixed it.

[Dan Chapman  (dpniel)]

Ok, just one more small issue I can see.

review: Needs Fixing

[Dan Chapman  (dpniel)]

LGTM

review: Approve

[Jenkins Bot (ubuntu-core-apps-jenkins-bot)]

review: Approve (continuous-integration)

=== modified file 'README'
--- README	2013-09-26 05:15:16 +0000
+++ README	2015-12-14 17:45:26 +0000
@@ -1,9 +1,23 @@
-Welcome the Ubuntu Calendar!
-
-Currently this application is fully implemented in QML/JS.
-All you need to launch this all is Qt5 and the qmlscene viewer:
+ReadMe - Ubuntu Calendar App 
+============================
+
+Ubuntu Calendar App is the official calendar app for Ubuntu Touch. We follow an open source model where the code is available to anyone to branch and to hack on. 
+The ubuntu calendaar app follows a test driven development (TDD) where tests are written in parallel to feature implementation to help spot regressions easier.
+
+Useful Links
+============
+
+Here are some useful links with regards to the Calendar App development.
+
+* Home Page      - https://developer.ubuntu.com/en/community/core-apps/calendar/
+* Calendar App Wiki - https://wiki.ubuntu.com/Touch/CoreApps/Calendar
+* Designs        - https://docs.google.com/presentation/d/14NIPecPFKb_8Ad3O4suEGJqVOw9bC4n0s63uWalbZ98/edit#slide=id.p
+* Project page   - https://launchpad.net/ubuntu-calendar-app
+
+Launch
+======
+This application is implemented in QML/JS.
+You need Qt5 and the qmlscene viewer to launch this application.
 
 $ cd ubuntu-calendar-app
 $ qmlscene calendar.qml
-
-To test the application on the device check out the "testrun.sh" script.

=== added file 'README.autopilot'
--- README.autopilot	1970-01-01 00:00:00 +0000
+++ README.autopilot	2015-12-14 17:45:26 +0000
@@ -0,0 +1,65 @@
+Running Autopilot tests
+=======================
+
+Ubuntu Calendar App follows a test driven development where autopilot tests are run before every merge into trunk.
+If you are submitting your bugfix/patch to the calendar app, please follow the following steps below to ensure that all tests pass before proposing a merge request.
+
+If you are looking for more info about Autopilot or writing AP tests for the calendar app, here are some useful links to help you:
+
+* http://developer.ubuntu.com/start/quality
+* https://developer.ubuntu.com/api/autopilot/python/1.5.0/
+
+For help and options on running tests, see:
+
+* https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/
+
+Prerequisites
+=============
+
+Install the following autopilot packages required to run the tests,
+    $ sudo apt-get install python3-autopilot libautopilot-qt ubuntu-ui-toolkit-autopilot python3-autopilot-vis
+
+address-book-service-testability package may also be required if not already installed
+   $ sudo apt-get install address-book-service-testability
+
+Running tests on the desktop
+============================
+
+Using terminal:
+
+*  Branch the calendar app code,
+    $ bzr branch lp:ubuntu-calendar-app
+
+*  Build the calendar app,
+    $ mkdir builddir && cd builddir
+    $ cmake ..  && make -j3
+    $ cd ..
+
+*  Navigate to the tests/autopilot directory.
+    $ cd tests/autopilot
+
+*  run all tests.
+    $ autopilot3 run -vv ubuntu_calendar_app
+
+    to list all tests:
+    $ autopilot3 list ubuntu_calendar_app
+
+    To run only one test (for instance: test_change_week_across_year in TestWeekview.py):
+    $ autopilot3 run -vv ubuntu_calendar_app.tests.test_weekview.TestWeekview.test_change_week_across_year 
+
+    Debugging tests using autopilot vis
+    $ autopilot3 launch -i Qt qmlscene ../../app/ubuntu-calendar-app.qml
+    $ autopilot3 vis
+
+Running tests using Ubuntu SDK
+==============================
+
+https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/
+
+Running tests on device or emulator
+===================================
+
+Using autopkg:
+
+1. navigate to the directory where the ubuntu-calendar-app branch is and run:
+  $ adt-run ubuntu-calendar-app --click=com.ubuntu.calendar --- ssh -s adb -p YOURPASSWORD

=== added file 'README.developers'
--- README.developers	1970-01-01 00:00:00 +0000
+++ README.developers	2015-12-14 17:45:26 +0000
@@ -0,0 +1,78 @@
+Building and running on Vivid Desktop (15.04)
+=============================================
+
+Building and running the Ubuntu Calendar App is quite simple. You will require
+Ubuntu 15.04 and higher to run on the desktop.
+
+   $ bzr branch lp:ubuntu-calendar-app branch-name
+   $ cd branch-name
+   $ mkdir builddir && cd builddir
+   $ cmake ..  && make -j3
+   $ qmlscene ../app/ubuntu-calendar-app.qml
+
+Submitting a patch upstream
+===========================
+
+If you want to submit a bug fix you can do so by branching the code as shown
+above, implementing the fixes and running to see if it fixed the issue. We also
+request that you run the Autopilot and Unit tests to check if anything
+regressed due to the bug fix.
+
+If the tests fail, you will have to fix them before your bug fix can be
+approved and merged into trunk. If the tests pass then commit and push your
+code by,
+
+   $ bzr commit -m "Implemented bug fix" --fixes lp:bug-number
+   $ bzr push lp:~launchpadid/ubuntu-calendar-app/branch-name
+
+Running Tests
+=============
+
+Please check README.autopilot and README.unittest on how to run the tests.
+They are quite explanatory and will help you get started.
+
+Code Style
+==========
+
+We are trying to use a common code style throughout the code base to maintain
+uniformity and improve code clarity. Listed below are the code styles guides
+that will be followed based on the language used.
+
+* QML        - http://qt-project.org/doc/qt-5/qml-codingconventions.html 
+* JS, C++    - https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
+* Python     - Code should follow PEP8 and Flake regulations
+
+Note: In the QML code convention, ignore the Javascript code section guidelines.
+So the sections that should be taken into account in the QML conventions are QML 
+Object Declarations, Grouped Properties and Lists.
+
+Debugging
+=========
+ 
+GDB allows one to see what is going on `inside' another program while it executes, 
+or what another program was doing at the moment it crashed. It is a pretty niffty tool which allows you 
+to get the crash log that can help a developer pin point the cause of the crash.
+Before reproducing crash it is good to create symbols table for gdb, by using command:
+
+   $ cd branch-name
+   $ mkdir builddir && cd builddir
+   $ cmake -DCMAKE_BUILD_TYPE=Debug .. && make -j3	
+
+To run GDB:
+
+   $ gdb qmlscene
+
+At this point, you are inside the gdb prompt. Run your application as you normally would.
+
+     run ../app/ubuntu-calendar-app.qml
+
+Your app is now running and monitored by GDB. Reproduce the steps in your app to make it crash. Once it does crash,
+
+     bt
+
+That's about it. To quit GDB, type quit to return back to the normal terminal console.
+
+     quit
+
+
+

=== added file 'README.mergeproposal'
--- README.mergeproposal	1970-01-01 00:00:00 +0000
+++ README.mergeproposal	2015-12-14 17:45:26 +0000
@@ -0,0 +1,31 @@
+Prerequisites to approving a Merge Proposal (MP)
+================================================
+
+Over time, it has been found that insufficient testing by reviewers sometimes
+leads to calendar app trunk not buildable in Qtcreator due to manifest errors, or
+translation pot file not updated. As such, please follow the checklist below
+before top-approving a MP.
+
+Checklist
+=========
+
+*   Does the MP add/remove user visible strings? If Yes, has the pot file been
+    updated?
+
+*   Does the MP change the UI? If Yes, has it been approved by design?
+
+*   Did you perform an exploratory manual test run of your code change and any
+    related functionality?
+
+*   If the MP fixes a bug or implements a feature, are there accompanying unit
+    and autopilot tests?
+
+*   Is the calendar app trunk buildable and runnable using Qtcreator?
+
+*   Was the debian changelog updated?
+
+*   Was the copyright years updated if necessary?
+
+The above checklist is more of a guideline to help calendar app trunk stay buildable,
+stable and up to date.
+

=== modified file 'README.translations'
--- README.translations	2014-10-17 05:49:22 +0000
+++ README.translations	2015-12-14 17:45:26 +0000
@@ -1,6 +1,7 @@
-# Updating translations
+Updating translations
+=====================
 
-Translations for the Calendar app happen in [Launchpad Translations][] and
+Translations for the Calendar app happen in [Launchpad Translations] and
 are automatically committed daily on the trunk branch in the po/ folder.
 
 They are then built and installed as part of the package build, so that
@@ -10,15 +11,19 @@
 translatable messages to translators. So whenever you add new translatable
 messages in the code, make sure to follow these steps:
 
- 1. Run click-buddy (or alternatively use cmake directly). E.g.:
-    `click-buddy --dir .`
- 2. Commit the generated .pot file:
-    `bzr commit -m"Updated translation template"`
- 3. Push the branch and send a merge proposal as usual
+ 1. Run click-buddy retaining the build directory:
+    $ click-buddy --dir . --no-clean
+ 2. Copy the .pot file from the <build dir> mentioned in the output to your
+    original source:
+    $ cp <build dir>/po/*.pot po/
+ 3. Commit the generated .pot file: 
+    $ bzr commit -m"Updated translation template"
+ 4. Push the branch and send a merge proposal as usual
 
 And that's it, once the branch lands Launchpad should take care of all the rest!
 
-# Behind the scenes
+Behind the scenes
+=================
 
 Behind the scenes, whenever the po/*.pot file (also known as translations template)
 is committed to trunk Launchpad reads it and updates the translatable strings

=== added file 'README.unittest'
--- README.unittest	1970-01-01 00:00:00 +0000
+++ README.unittest	2015-12-14 17:45:26 +0000
@@ -0,0 +1,39 @@
+Running QML Unit Tests
+======================
+
+QML Unit Tests help with testing the internal working of components while
+autopilot tests help with testing the UI workflow as experience by the user.
+Running QML tests is quite simple and very fast.
+
+If you are submitting your bugfix/patch to the calendar app, please follow the
+following steps below to check whether that all tests pass before proposing a
+merge request.
+
+* Branch the calendar app code, 
+   $ bzr branch lp:ubuntu-calendar-app
+
+   $ mkdir builddir && cd builddir
+   $ cmake ..  && make -j3
+   
+Running all unit test at once
+=============================
+
+If you want to run all tests, then run the following command from the builddir,
+
+   $ ctest --output-on-failure
+   
+If you want more verbose output, then run,
+
+   $ ctest -VV
+
+Running individual test cases,
+==============================
+
+If you want to run testcases individually, you can do so by navigating to the
+unit tests folder by,
+
+* Navigate to the tests/unit directory
+   $ cd tests/unittests
+   
+* Run the test by providing their filenames
+   $ qmltestrunner tst_date.qml