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

[Girish]

Updated README, README.autopilot, README.translations.
Added README.developers, README.mergeproposal

[Andrew Hayzen (ahayzen)]

Awesome! As discussed, can we make this into markdown format so that this could then be automatically parsed on sites such as developer.ubuntu.com and ensures a consistent format for use across all core apps.

I think most of it already is markdown? But I'll just let you confirm that it is, some of the sections like the bash commands I wonder if there is a markdown format for that?

review: Needs Information

[Andrew Hayzen (ahayzen)]

I believe this has been superseded by [0], therefore I am rejecting this merge proposal.

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

review: Disapprove

Unmerged revisions

189. By Girish on 2015-12-16

Minor changes in README.developers

188. By Girish on 2015-12-16

Expanded and updated READMEs

=== modified file 'README'
--- README	2015-11-09 10:37:47 +0000
+++ README	2015-12-16 20:34:26 +0000
@@ -1,20 +1,36 @@
-Weather app for Ubuntu devices
-
-To contribute:
-    https://wiki.ubuntu.com/Touch/CoreApps/Weather
-    https://wiki.ubuntu.com/Touch/CoreApps/DevelopmentGuide
-
-Note: The OpenWeatherMap service now requires an API key where previously
-      it did not. FOSS developers can register for a free API key
-      which needs to be put into app/data/keys.js for the app to 
-      function correctly. Do not commit branches with the key in place
-      as a centrally managed key is injected at build time.
-
-      See http://openweathermap.org/faq#error401 for details and
-      http://openweathermap.org/appid to obtain a personal key.
-
-The following essential packages are required to develop this app:
-- ubuntu-sdk (see http://developer.ubuntu.com/start)
-- intltool - run the `sudo apt-get install intltool` command for installation
-
-See the debian/control file for an up-to-date list of dependencies
+ReadMe - Ubuntu Weather App
+===========================
+Ubuntu Weather App is the official weather app for Ubuntu Touch. We follow an open
+source model where the code is available to anyone to branch and hack on. The
+ubuntu weather app follows a test driven development (TDD) where tests are
+written in parallel to feature implementation to help spot regressions easier.
+
+API
+===
+The OpenWeatherMap service requires an API key. 
+Visit http://openweathermap.org/appid to obtain a personal key.
+Visit http://openweathermap.org/faq#error401 for more details.
+Place the keys in app/data/keys.js
+
+Do not commit branches with the key in place as a centrally managed key is injected at build time.
+
+Dependencies
+============
+DEPENDENCIES ARE NEEDED TO BE INSTALLED TO BUILD AND RUN THE APP.
+
+A complete list of dependencies for the project can be found in ubuntu-weather-app/debian/control
+
+The following essential packages are also required to develop this app:
+* ubuntu-sdk - http://developer.ubuntu.com/start
+* intltool   - run the `sudo apt-get install intltool` command for installation
+
+Useful Links
+============
+Here are some useful links with regards to the Weather App development.
+
+* Home Page        - https://developer.ubuntu.com/en/community/core-apps/weather/
+* Weather App Wiki - https://wiki.ubuntu.com/Touch/CoreApps/Weather
+
+* Designs          - https://docs.google.com/presentation/d/1tXcyMBvJAYvwFvUAmTTYzmBP2NFQgbG_Gy8e2gv91kU/edit#slide=id.p
+
+* Project page     - https://launchpad.net/ubuntu-weather-app
 
=== modified file 'README.autopilot'
--- README.autopilot	2015-07-23 00:36:06 +0000
+++ README.autopilot	2015-12-16 20:34:26 +0000
@@ -1,4 +1,5 @@
-# Running Autopilot tests
+Running Autopilot tests
+=======================
 
 The Weather 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 Weather app, please follow the following steps below to ensure that all tests pass before proposing a merge request.
 
@@ -11,12 +12,14 @@
 
 - https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/
 
-## Prerequisites
+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
+Running tests on the desktop
+============================
 
 Using terminal:
 
@@ -39,8 +42,13 @@
     $ autopilot3 launch -i Qt qmlscene app/ubuntu-weather-app.qml
     $ autopilot3 vis
 
-
-## Running tests on device or emulator:
+Running tests using Ubuntu SDK
+==============================
+
+Refer this tutorial to run tests on Ubuntu SDK: https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/
+
+Running tests on device or emulator:
+====================================
 
 Using autopkg:
 
 
=== added file 'README.developers'
--- README.developers	1970-01-01 00:00:00 +0000
+++ README.developers	2015-12-16 20:34:26 +0000
@@ -0,0 +1,78 @@
+Building and running on Vivid Desktop (15.04)
+=============================================
+
+Building and running the Ubuntu Weather App is quite simple. You will require
+Ubuntu 15.04 and higher to run on the desktop.
+
+   $ bzr branch lp:ubuntu-weather-app branch-name
+   $ cd branch-name
+   $ mkdir builddir && cd builddir
+   $ cmake ..  && make -j3
+   $ qmlscene ../app/ubuntu-weather-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 Autopilottests 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-weather-app/branch-name
+
+Running Tests
+=============
+
+Please check README.autopilot 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-weather-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-16 20:34:26 +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 weather 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?
+
+*   Did you remove the API key? (refer README)
+
+*   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 weather 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 weather app trunk stay buildable,
+stable and up to date.
+
 
=== modified file 'README.translations'
--- README.translations	2015-05-14 23:34:48 +0000
+++ README.translations	2015-12-16 20:34:26 +0000
@@ -1,4 +1,5 @@
-# Updating translations
+Updating translations
+=====================
 
 Translations for the Weather app happen in [Launchpad Translations][] and
 are automatically committed daily on the trunk branch in the po/ folder.
@@ -18,7 +19,8 @@
 
 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