Merge lp:~emailgirishrawat/ubuntu-weather-app/markdown-readmes into lp:ubuntu-weather-app

[Girish]

Updated and fixed READMEs.

Marked down all the READMEs. Minor changes in README-Developers.md.

[Nicholas Skaggs (nskaggs)]

I'll leave the final approval to Andrew, but this looks like a nice improvement.

[Nicholas Skaggs (nskaggs)]

review: Approve

[Victor Thompson (vthompson)]

Hi Girish! Thanks for helping to get these updated! Good work! I have some inline comments that I'd like you too look into, please.

One general question for Andrew and Nicholas (and others): Should we perhaps remove the section on debugging with GDB? It doesn't seem as applicable for a pure QML app--I've never had to run gdb while running a QML app.

review: Needs Fixing

[Andrew Hayzen (ahayzen)]

Looking pretty good so far, a few (8) inline comments :-)

review: Needs Fixing

[Girish (emailgirishrawat)]

ahayzen : vthompson : Fixed.
ahayzen : I couldn't find a wiki for the weather app's design specs.

[Andrew Hayzen (ahayzen)]

One inline comment

1) We now have (or popey is adding as we speak :-) ) https://developer.ubuntu.com/en/community/core-apps/weather/#design so could this be updated :-)

review: Needs Fixing

[Girish (emailgirishrawat)]

Andrew, the link to design leads to the main page. It's doesn't even lead to the design section on the page.
Nevertheless, I've made the changes.

[Andrew Hayzen (ahayzen)]

LGTM, thanks for your patience and great work :-) I'll let Victor also approve before it is merged in.

review: Approve

[Victor Thompson (vthompson)]

LGTM! THanks Girish!

review: Approve

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

FAILED: Autolanding.
No commit message was specified in the merge proposal. Hit 'Add commit message' on the merge proposal web page or follow the link below. You can approve the merge proposal yourself to rerun.
https://code.launchpad.net/~emailgirishrawat/ubuntu-weather-app/markdown-readmes/+merge/280787/+edit-commit-message

review: Needs Fixing (continuous-integration)

[Girish (emailgirishrawat)]

Victor: Could you approve this again? Forgot to add a commit message the previous time.

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

review: Approve (continuous-integration)

=== removed file 'README'
--- README	2015-11-09 10:37:47 +0000
+++ README	1970-01-01 00:00:00 +0000
@@ -1,20 +0,0 @@
-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

=== added file 'README-Autopilot.md'
--- README-Autopilot.md	1970-01-01 00:00:00 +0000
+++ README-Autopilot.md	2015-12-21 12:54:41 +0000
@@ -0,0 +1,78 @@
+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.
+
+If you are looking for more info about Autopilot or writing AP tests for the weather 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 Weather app code, for example,
+
+    $ bzr branch lp:ubuntu-weather-app
+    
+*  Navigate to the tests/autopilot directory.
+
+$ cd ubuntu-weather-app/tests/autopilot
+
+*  run all tests.
+
+    $ autopilot3 run -vv ubuntu_weather_app
+
+* to list all tests:
+
+    $ autopilot3 list ubuntu_weather_app
+
+ To run only one test (for instance: ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button)
+
+    $ autopilot3 run -vv ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button
+
+* Debugging tests using autopilot vis
+
+    $ autopilot3 launch -i Qt qmlscene app/ubuntu-weather-app.qml
+
+    $ autopilot3 vis
+
+Running tests using Ubuntu SDK
+==============================
+
+Refer this [tutorial](https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/) to run tests on Ubuntu SDK: 
+
+Running tests on device or emulator:
+====================================
+
+Using autopkg:
+
+*  Branch the Weather app code, for example,
+
+    $ bzr branch lp:ubuntu-weather-app
+
+*  Navigate to the source directory.
+
+    $ cd ubuntu-weather-app
+
+*  Build a click package
+    
+    $ click-buddy .
+
+*  Run the tests on device (assumes only one click package in the directory)
+
+$ adt-run . *.click --- ssh -s adb -- -p <PASSWORD>
+

=== added file 'README-Developers.md'
--- README-Developers.md	1970-01-01 00:00:00 +0000
+++ README-Developers.md	2015-12-21 12:54:41 +0000
@@ -0,0 +1,91 @@
+Building and running on Desktop
+===============================
+
+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
+    $ qmlscene app/ubuntu-weather-app.qml
+
+API
+===
+The OpenWeatherMap service requires an API key. 
+Visit [Open Weather](http://openweathermap.org/appid) to obtain a personal key.
+Click [here](http://openweathermap.org/faq#error401) for more details.
+Place the key between the quotation marks for the "owmKey" variable in app/data/keys.js
+
+**Do not commit branches with the key in place as a centrally managed key is injected at build time.**
+
+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 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-weather-app/branch-name
+
+Running Tests
+=============
+
+Please check README-Autopilot.md 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	
+
+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.md'
--- README-Mergeproposal.md	1970-01-01 00:00:00 +0000
+++ README-Mergeproposal.md	2015-12-21 12:54:41 +0000
@@ -0,0 +1,30 @@
+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.md)
+
+*   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.
+

=== added file 'README-Translations.md'
--- README-Translations.md	1970-01-01 00:00:00 +0000
+++ README-Translations.md	2015-12-21 12:54:41 +0000
@@ -0,0 +1,35 @@
+Updating translations
+=====================
+
+Translations for the Weather app happen in [Launchpad Translations](https://translations.launchpad.net/ubuntu-weather-app) 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
+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 to build the project and generate a new .pot file:
+    $ 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
+
+And that's it, once the branch lands Launchpad should take care of all the rest!
+
+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 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 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](https://www.gnu.org/software/gettext/).
+
+ [Launchpad Translations](https://translations.launchpad.net/ubuntu-weather-app)
+ [Gettext format](https://www.gnu.org/software/gettext/)

=== removed file 'README.autopilot'
--- README.autopilot	2015-07-23 00:36:06 +0000
+++ README.autopilot	1970-01-01 00:00:00 +0000
@@ -1,57 +0,0 @@
-# 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.
-
-If you are looking for more info about Autopilot or writing AP tests for the weather 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 Weather app code, for example,
-    $ bzr branch lp:ubuntu-weather-app
-    
-*  Navigate to the tests/autopilot directory.
-    $ cd ubuntu-weather-app/tests/autopilot
-
-*  run all tests.
-    $ autopilot3 run -vv ubuntu_weather_app
-
-    to list all tests:
-    $ autopilot3 list ubuntu_weather_app
-
-    To run only one test (for instance: ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button)
-    $ autopilot3 run -vv ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button
-
-    Debugging tests using autopilot vis
-    $ autopilot3 launch -i Qt qmlscene app/ubuntu-weather-app.qml
-    $ autopilot3 vis
-
-
-## Running tests on device or emulator:
-
-Using autopkg:
-
-*  Branch the Weather app code, for example,
-    $ bzr branch lp:ubuntu-weather-app
-
-*  Navigate to the source directory.
-    $ cd ubuntu-weather-app
-
-*  Build a click package
-    $ click-buddy .
-
-*  Run the tests on device (assumes only one click package in the directory)
-    $ adt-run . *.click --- ssh -s adb -- -p <PASSWORD>

=== added file 'README.md'
--- README.md	1970-01-01 00:00:00 +0000
+++ README.md	2015-12-21 12:54:41 +0000
@@ -0,0 +1,34 @@
+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 [Open Weather](http://openweathermap.org/appid) to obtain a personal key.
+Click [here](http://openweathermap.org/faq#error401) for more details.
+Place the key between the quotation marks for the "owmKey" variable 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  `sudo apt-get install intltool` 
+
+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://developer.ubuntu.com/en/community/core-apps/weather/#design)
+* [Project page](https://launchpad.net/ubuntu-weather-app) 

=== removed file 'README.translations'
--- README.translations	2015-05-14 23:34:48 +0000
+++ README.translations	1970-01-01 00:00:00 +0000
@@ -1,37 +0,0 @@
-# Updating translations
-
-Translations for the Weather 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
-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 to build the project and generate a new .pot file:
-    `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
-
-And that's it, once the branch lands Launchpad should take care of all the rest!
-
-# 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
-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 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-weather-app
- [gettext format]: https://www.gnu.org/software/gettext/

=== modified file 'debian/changelog'
--- debian/changelog	2015-12-03 15:22:45 +0000
+++ debian/changelog	2015-12-21 12:54:41 +0000
@@ -1,7 +1,11 @@
 ubuntu-weather-app (3.2) UNRELEASED; urgency=medium
 
+  [ Andrew Hayzen ]
   * Release 3.1 and bump version to 3.2
 
+  [ Girish Rawat ]
+  * Added new READMEs
+
  -- Andrew Hayzen <[e-mail]>  Thu, 03 Dec 2015 15:20:49 +0000
 
 ubuntu-weather-app (3.1ubuntu1) vivid; urgency=medium