ubuntu-touch-coreapps-reviewers team mailing list archive

[Aditya <dtrg21@xxxxxxxxx>]

Aditya has proposed merging lp:~dtrg21/ubuntu-rssreader-app/add-readmes into lp:ubuntu-rssreader-app.

Requested reviews:
  Nicholas Skaggs (nskaggs): google code in

For more details, see:
https://code.launchpad.net/~dtrg21/ubuntu-rssreader-app/add-readmes/+merge/281191

Add readme's for Google Code In task.
-- 
Your team Ubuntu Shorts Developers is subscribed to branch lp:ubuntu-rssreader-app.

=== added file 'README'
--- README	1970-01-01 00:00:00 +0000
+++ README	2015-12-22 10:10:10 +0000
@@ -0,0 +1,17 @@
+ReadMe - Ubuntu Shorts App
+=========================
+
+Ubuntu Shorts App is the official rss reader app for Ubuntu Touch. We follow an open
+source model where the code is available to anyone to branch and hack on. The
+ubuntu shorts 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 Clock App development.
+
+* Home Page      - https://developer.ubuntu.com/en/community/core-apps/shorts/
+* Project page   - https://launchpad.net/ubuntu-rssreader-app
+
+

=== added file 'README.autopilot'
--- README.autopilot	1970-01-01 00:00:00 +0000
+++ README.autopilot	2015-12-22 10:10:10 +0000
@@ -0,0 +1,52 @@
+Running Autopilot tests
+=======================
+
+Ubuntu Shorts 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 shorts 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
+shorts 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
+
+Running tests on the desktop
+============================
+
+Using terminal:
+
+*  Branch the shorts app code,
+    $ bzr branch lp:ubuntu-rssreader-app
+
+*  Build the shorts app,
+    $ mkdir builddir && cd builddir
+    $ cmake .. && cmake --build . -- -j 3
+    $ cd ..
+
+*  Navigate to the tests/autopilot directory.
+    $ cd shorts/tests/autopilot
+
+*  run all tests.
+    $ autopilot3 run -vv shorts_app
+
+    to list all tests:
+    $ autopilot3 list shorts_app
+
+    To run only one test (for instance: test_add_single_type_alarm_must_add_to_alarm_list in TestAlarm.py):
+    $ autopilot3 run -vv ubuntu_shorts_app.tests.test_alarm.TestMainWindow.test_add_feed_to_new_topic
+
+    Debugging tests using autopilot vis
+    $ autopilot3 launch -i Qt qmlscene shorts/qml/shorts-app.qml -I shorts
+    $ autopilot3 vis

=== added file 'README.developers'
--- README.developers	1970-01-01 00:00:00 +0000
+++ README.developers	2015-12-22 10:10:10 +0000
@@ -0,0 +1,78 @@
+Building and running on Vivid Desktop (15.04)
+=============================================
+
+Building and running the Ubuntu Shorts App is quite simple. You will require
+Ubuntu 15.04 and higher to run on the desktop.
+
+   $ bzr branch lp:ubuntu-rssreader-app branch-name
+   $ cd branch-name
+   $ mkdir builddir && cd builddir
+   $ cmake .. && cmake --build . -- -j 3
+   $ qmlscene ../shorts/qml/shorts-app.qml -I ../shorts/
+
+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-rssreader-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 .. && cmake --build . -- -j 3
+
+To run GDB:
+
+   $ gdb qmlscene
+
+At this point, you are inside the gdb prompt. Run your application as you normally would.
+
+     run ../shorts/qml/shorts-app.qml -I ../shorts
+
+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-22 10:10:10 +0000
@@ -0,0 +1,33 @@
+Prerequisites to approving a Merge Proposal (MP)
+================================================
+
+Over time, it has been found that insufficient testing by reviewers sometimes
+leads to shorts 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 shorts 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 shorts app trunk stay buildable,
+stable and up to date.
+
+Note: As of vivid 15.04, Autopilot are broken in trunk. As such autopilot failures
+can be excused until they are fixed in trunk.

=== added file 'README.translations'
--- README.translations	1970-01-01 00:00:00 +0000
+++ README.translations	2015-12-22 10:10:10 +0000
@@ -0,0 +1,42 @@
+Updating translations
+=====================
+
+Translations for the Shorts app happen in [Launchpad Translations] and
+are automatically committed daily on the trunk branch in the shorts/po/ folder.
+
+They are then built and installed as part of the package build, so that
+developers don't really need to worry about them.
+
+However, there is one task that needs to be taken care of: exposing new
+translatable messages to translators. So whenever you add new translatable
+messages in the code, make sure to follow these steps:
+
+ 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>/shorts/po/*.pot shorts/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, whenever the shorts/po/*.pot file (also known as translations template)
+is committed to trunk Launchpad reads it and updates the translatable strings
+exposed in the web UI. This will enable translators to work on the new strings.
+The translations template contains all translatable strings that have been
+extracted from the source code files.
+
+Launchpad will then store translations in its database and will commit them daily
+in the form of textual shorts/po/*.po files to trunk. The PO files are also usually
+referred to as the translations files. You'll find a translation file for each
+language the app has got at least a translated message available for.
+
+Translations for core apps follow the standard [gettext format].
+
+ [Launchpad Translations]: https://translations.launchpad.net/ubuntu-rssreader-app
+ [gettext format]: https://www.gnu.org/software/gettext/

=== removed file 'README.txt'
--- README.txt	2015-07-04 08:38:18 +0000
+++ README.txt	1970-01-01 00:00:00 +0000
@@ -1,14 +0,0 @@
- **** README for Joey ****
-
-Now project has following structure:
-
-|---shorts-app
- 	|---shorts
- 	|	|---- * sources *
- 	|--- * some configuration files * (Let me call it "qmake configuration files, qcf")
-
-We decided to keep both CMake and qmake working in parallel, so here is my plan - you should put your CMake configuration files (ccf) inside "shorts" folder (near to sources), and do not touch qcf at root folder. In such case they can work together - qmake for develiping, CMake for autotests and so on. 
-
-
-
-Next idea - we should use name "shorts" whenever it possible. In trunk of "ubuntu-rssreader-app" already a lot of things called "shorts" (for example main qml file or *.apparmor file). But we must use "ubuntu-rssreader-app" as name of our project in launchpad. In all other places I prefer "shorts".

=== added file 'README.unittest'
--- README.unittest	1970-01-01 00:00:00 +0000
+++ README.unittest	2015-12-22 10:10:10 +0000
@@ -0,0 +1,41 @@
+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 clock app, please follow the
+following steps below to check whether that all tests pass before proposing a
+merge request.
+
+* Branch the clock app code, 
+   $ bzr branch lp:ubuntu-rssreader-app
+
+* Build the clock app,
+   $ mkdir builddir && cd builddir
+   $ cmake ..  && cmake --build . -- -j 3
+   
+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 shorts/tests/unit
+   
+* Run the test by providing their filenames
+   $ qmltestrunner -input tst_feedLabel.qml
+   $ qmltestrunner -input tst_alarm.qml -import ../../shorts