Merge lp:~dtrg21/ubuntu-rssreader-app/add-readmes into lp:ubuntu-rssreader-app

[Aditya]

Add readme's for Google Code In task.

Add readme's for Google Code In task.

[Joey Chan (qqworini)]

I'm OK with this MR

review: Approve

[Andrew Hayzen (ahayzen)]

Looks good so far! However for weather [0] we decided to use the markdown format, so that would mean renaming the files and updating some of the links to be in the format [Title](URL). I believe that we should be consistent over the coreapps, what do you guys think?

0 - https://code.launchpad.net/~emailgirishrawat/ubuntu-weather-app/markdown-readmes

review: Needs Information

[lp:~dtrg21/ubuntu-rssreader-app/add-readmes]

416. By Aditya on 2015-12-23

Add README's as MarkDown. Task from Google Code In

[Aditya (dtrg21)]

I have added them as markdowns. Check it now.

[Andrew Hayzen (ahayzen)]

Awesome thanks, look much better, the web links could do with titles next to them though, I've put an example inline comment next to each one that should be updated.

Also I have one other comment for the README-developers.md

'Not sure if we should directly refer to "Vivid Desktop (15.04)", maybe just "Desktop" is better, otherwise this will have to be updated.'

Otherwise this looks good :-)

review: Needs Fixing

[lp:~dtrg21/ubuntu-rssreader-app/add-readmes]

417. By Aditya on 2015-12-23

Fix links

[Aditya (dtrg21)]

Here is the final edit.

[Andrew Hayzen (ahayzen)]

Awesome, thanks for those extra changes :-)

I'll let Joey do the final top approval.

review: Approve

[Andrew Hayzen (ahayzen)]

Oh you could add yourself to the debian/changelog if you wanted :-)

Just run $ dch

[Nicholas Skaggs (nskaggs)]

It seems this never actually landed in trunk! Whoops, let's get this top approved and landed!

review: Approve

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

review: Approve (continuous-integration)

=== added file 'README-Autopilot.md'
--- README-Autopilot.md	1970-01-01 00:00:00 +0000
+++ README-Autopilot.md	2015-12-23 16:58:29 +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:
+
+* [Ubuntu - Quality](http://developer.ubuntu.com/start/quality)
+* [Ubuntu - Autopilot](https://developer.ubuntu.com/api/autopilot/python/1.5.0/)
+
+For help and options on running tests, see:
+
+* [Autopilot Tests](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.md'
--- README-Developers.md	1970-01-01 00:00:00 +0000
+++ README-Developers.md	2015-12-23 16:58:29 +0000
@@ -0,0 +1,78 @@
+Building and running on Desktop
+=============================================
+
+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.md'
--- README-MergeProposal.md	1970-01-01 00:00:00 +0000
+++ README-MergeProposal.md	2015-12-23 16:58:29 +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-UnitTest.md'
--- README-UnitTest.md	1970-01-01 00:00:00 +0000
+++ README-UnitTest.md	2015-12-23 16:58:29 +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
 
=== added file 'README-translations.md'
--- README-translations.md	1970-01-01 00:00:00 +0000
+++ README-translations.md	2015-12-23 16:58:29 +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/)
 
=== added file 'README.md'
--- README.md	1970-01-01 00:00:00 +0000
+++ README.md	2015-12-23 16:58:29 +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)
+
+
 
=== 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".