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

Proposed by Girish on 2015-12-17
Status: Merged
Approved by: Victor Thompson on 2015-12-22
Approved revision: 191
Merged at revision: 188
Proposed branch: lp:~emailgirishrawat/ubuntu-weather-app/markdown-readmes
Merge into: lp:ubuntu-weather-app
Diff against target: 437 lines (+272/-114)
9 files modified
README (+0/-20)
README-Autopilot.md (+78/-0)
README-Developers.md (+91/-0)
README-Mergeproposal.md (+30/-0)
README-Translations.md (+35/-0)
README.autopilot (+0/-57)
README.md (+34/-0)
README.translations (+0/-37)
debian/changelog (+4/-0)
To merge this branch: bzr merge lp:~emailgirishrawat/ubuntu-weather-app/markdown-readmes
Reviewer Review Type Date Requested Status
Jenkins Bot continuous-integration Approve on 2015-12-22
Victor Thompson Approve on 2015-12-22
Andrew Hayzen Approve on 2015-12-21
Nicholas Skaggs (community) 2015-12-17 Approve on 2015-12-17
Review via email: mp+280787@code.launchpad.net

Commit message

Updated and fixed READMEs.

Description of the change

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

To post a comment you must log in.
Nicholas Skaggs (nskaggs) wrote :

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

Nicholas Skaggs (nskaggs) :
review: Approve
Victor Thompson (vthompson) wrote :

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) wrote :

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

review: Needs Fixing
Girish (emailgirishrawat) wrote :

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

Andrew Hayzen (ahayzen) wrote :

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) wrote :

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) wrote :

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

review: Approve
Victor Thompson (vthompson) wrote :

LGTM! THanks Girish!

review: Approve

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) wrote :

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

review: Approve (continuous-integration)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== removed file 'README'
2--- README 2015-11-09 10:37:47 +0000
3+++ README 1970-01-01 00:00:00 +0000
4@@ -1,20 +0,0 @@
5-Weather app for Ubuntu devices
6-
7-To contribute:
8- https://wiki.ubuntu.com/Touch/CoreApps/Weather
9- https://wiki.ubuntu.com/Touch/CoreApps/DevelopmentGuide
10-
11-Note: The OpenWeatherMap service now requires an API key where previously
12- it did not. FOSS developers can register for a free API key
13- which needs to be put into app/data/keys.js for the app to
14- function correctly. Do not commit branches with the key in place
15- as a centrally managed key is injected at build time.
16-
17- See http://openweathermap.org/faq#error401 for details and
18- http://openweathermap.org/appid to obtain a personal key.
19-
20-The following essential packages are required to develop this app:
21-- ubuntu-sdk (see http://developer.ubuntu.com/start)
22-- intltool - run the `sudo apt-get install intltool` command for installation
23-
24-See the debian/control file for an up-to-date list of dependencies
25
26=== added file 'README-Autopilot.md'
27--- README-Autopilot.md 1970-01-01 00:00:00 +0000
28+++ README-Autopilot.md 2015-12-21 12:54:41 +0000
29@@ -0,0 +1,78 @@
30+Running Autopilot tests
31+=======================
32+
33+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.
34+
35+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:
36+
37+- [Ubuntu - Quality](http://developer.ubuntu.com/start/quality)
38+- [Ubuntu - Autopilot](https://developer.ubuntu.com/api/autopilot/python/1.5.0/)
39+
40+For help and options on running tests, see:
41+
42+- [Autopilot Tests](https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/)
43+
44+Prerequisites
45+=============
46+
47+Install the following autopilot packages required to run the tests,
48+
49+ $ sudo apt-get install python3-autopilot libautopilot-qt ubuntu-ui-toolkit-autopilot python3-autopilot-vis
50+
51+Running tests on the desktop
52+============================
53+
54+Using terminal:
55+
56+* Branch the Weather app code, for example,
57+
58+ $ bzr branch lp:ubuntu-weather-app
59+
60+* Navigate to the tests/autopilot directory.
61+
62+$ cd ubuntu-weather-app/tests/autopilot
63+
64+* run all tests.
65+
66+ $ autopilot3 run -vv ubuntu_weather_app
67+
68+* to list all tests:
69+
70+ $ autopilot3 list ubuntu_weather_app
71+
72+ To run only one test (for instance: ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button)
73+
74+ $ autopilot3 run -vv ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button
75+
76+* Debugging tests using autopilot vis
77+
78+ $ autopilot3 launch -i Qt qmlscene app/ubuntu-weather-app.qml
79+
80+ $ autopilot3 vis
81+
82+Running tests using Ubuntu SDK
83+==============================
84+
85+Refer this [tutorial](https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/) to run tests on Ubuntu SDK:
86+
87+Running tests on device or emulator:
88+====================================
89+
90+Using autopkg:
91+
92+* Branch the Weather app code, for example,
93+
94+ $ bzr branch lp:ubuntu-weather-app
95+
96+* Navigate to the source directory.
97+
98+ $ cd ubuntu-weather-app
99+
100+* Build a click package
101+
102+ $ click-buddy .
103+
104+* Run the tests on device (assumes only one click package in the directory)
105+
106+$ adt-run . *.click --- ssh -s adb -- -p <PASSWORD>
107+
108
109=== added file 'README-Developers.md'
110--- README-Developers.md 1970-01-01 00:00:00 +0000
111+++ README-Developers.md 2015-12-21 12:54:41 +0000
112@@ -0,0 +1,91 @@
113+Building and running on Desktop
114+===============================
115+
116+Building and running the Ubuntu Weather App is quite simple. You will require
117+Ubuntu 15.04 and higher to run on the desktop.
118+
119+
120+
121+ $ bzr branch lp:ubuntu-weather-app branch-name
122+ $ cd branch-name
123+ $ qmlscene app/ubuntu-weather-app.qml
124+
125+API
126+===
127+The OpenWeatherMap service requires an API key.
128+Visit [Open Weather](http://openweathermap.org/appid) to obtain a personal key.
129+Click [here](http://openweathermap.org/faq#error401) for more details.
130+Place the key between the quotation marks for the "owmKey" variable in app/data/keys.js
131+
132+**Do not commit branches with the key in place as a centrally managed key is injected at build time.**
133+
134+Submitting a patch upstream
135+===========================
136+
137+If you want to submit a bug fix you can do so by branching the code as shown
138+above, implementing the fixes and running to see if it fixed the issue. We also
139+request that you run the Autopilot tests to check if anything
140+regressed due to the bug fix.
141+
142+If the tests fail, you will have to fix them before your bug fix can be
143+approved and merged into trunk. If the tests pass then commit and push your
144+code by,
145+
146+
147+
148+ $ bzr commit -m "Implemented bug fix" --fixes lp:bug-number
149+ $ bzr push lp:~launchpadid/ubuntu-weather-app/branch-name
150+
151+Running Tests
152+=============
153+
154+Please check README-Autopilot.md on how to run the tests.
155+They are quite explanatory and will help you get started.
156+
157+Code Style
158+==========
159+
160+We are trying to use a common code style throughout the code base to maintain
161+uniformity and improve code clarity. Listed below are the code styles guides
162+that will be followed based on the language used.
163+
164+* [QML](http://qt-project.org/doc/qt-5/qml-codingconventions.html)
165+* [JS, C++](https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml)
166+* Python - Code should follow PEP8 and Flake regulations
167+
168+Note: In the QML code convention, ignore the Javascript code section guidelines.
169+So the sections that should be taken into account in the QML conventions are QML
170+Object Declarations, Grouped Properties and Lists.
171+
172+Debugging
173+=========
174+
175+GDB allows one to see what is going on `inside' another program while it executes,
176+or what another program was doing at the moment it crashed. It is a pretty niffty tool which allows you
177+to get the crash log that can help a developer pin point the cause of the crash.
178+Before reproducing crash it is good to create symbols table for gdb, by using command:
179+
180+
181+
182+ $ cd branch-name
183+
184+To run GDB:
185+
186+
187+
188+ $ gdb qmlscene
189+
190+At this point, you are inside the gdb prompt. Run your application as you normally would.
191+
192+ run app/ubuntu-weather-app.qml
193+
194+Your app is now running and monitored by GDB. Reproduce the steps in your app to make it crash. Once it does crash,
195+
196+ bt
197+
198+That's about it. To quit GDB, type quit to return back to the normal terminal console.
199+
200+ quit
201+
202+
203+
204
205=== added file 'README-Mergeproposal.md'
206--- README-Mergeproposal.md 1970-01-01 00:00:00 +0000
207+++ README-Mergeproposal.md 2015-12-21 12:54:41 +0000
208@@ -0,0 +1,30 @@
209+Prerequisites to approving a Merge Proposal (MP)
210+================================================
211+
212+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.
213+
214+Checklist
215+=========
216+
217+* Does the MP add/remove user visible strings? If Yes, has the pot file been
218+ updated?
219+
220+* Did you remove the API key? (refer README.md)
221+
222+* Does the MP change the UI? If Yes, has it been approved by design?
223+
224+* Did you perform an exploratory manual test run of your code change and any
225+ related functionality?
226+
227+* If the MP fixes a bug or implements a feature, are there accompanying unit
228+ and autopilot tests?
229+
230+* Is the weather app trunk buildable and runnable using Qtcreator?
231+
232+* Was the debian changelog updated?
233+
234+* Was the copyright years updated if necessary?
235+
236+The above checklist is more of a guideline to help weather app trunk stay buildable,
237+stable and up to date.
238+
239
240=== added file 'README-Translations.md'
241--- README-Translations.md 1970-01-01 00:00:00 +0000
242+++ README-Translations.md 2015-12-21 12:54:41 +0000
243@@ -0,0 +1,35 @@
244+Updating translations
245+=====================
246+
247+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.
248+
249+They are then built and installed as part of the package build, so that
250+developers don't really need to worry about them.
251+
252+However, there is one task that needs to be taken care of: exposing new
253+translatable messages to translators. So whenever you add new translatable
254+messages in the code, make sure to follow these steps:
255+
256+ 1. Run click-buddy to build the project and generate a new .pot file:
257+ $ click-buddy --dir .
258+ 2. Commit the generated .pot file:
259+ $ bzr commit -m"Updated translation template"
260+ 3. Push the branch and send a merge proposal as usual
261+
262+And that's it, once the branch lands Launchpad should take care of all the rest!
263+
264+Behind the scenes
265+=================
266+
267+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.
268+The translations template contains all translatable strings that have been
269+extracted from the source code files.
270+
271+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
272+referred to as the translations files. You'll find a translation file for each
273+language the app has got at least a translated message available for.
274+
275+Translations for core apps follow the standard [gettext format](https://www.gnu.org/software/gettext/).
276+
277+ [Launchpad Translations](https://translations.launchpad.net/ubuntu-weather-app)
278+ [Gettext format](https://www.gnu.org/software/gettext/)
279
280=== removed file 'README.autopilot'
281--- README.autopilot 2015-07-23 00:36:06 +0000
282+++ README.autopilot 1970-01-01 00:00:00 +0000
283@@ -1,57 +0,0 @@
284-# Running Autopilot tests
285-
286-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.
287-
288-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:
289-
290-- http://developer.ubuntu.com/start/quality
291-- https://developer.ubuntu.com/api/autopilot/python/1.5.0/
292-
293-For help and options on running tests, see:
294-
295-- https://developer.ubuntu.com/en/start/platform/guides/running-autopilot-tests/
296-
297-## Prerequisites
298-
299-Install the following autopilot packages required to run the tests,
300-$ sudo apt-get install python3-autopilot libautopilot-qt ubuntu-ui-toolkit-autopilot python3-autopilot-vis
301-
302-## Running tests on the desktop
303-
304-Using terminal:
305-
306-* Branch the Weather app code, for example,
307- $ bzr branch lp:ubuntu-weather-app
308-
309-* Navigate to the tests/autopilot directory.
310- $ cd ubuntu-weather-app/tests/autopilot
311-
312-* run all tests.
313- $ autopilot3 run -vv ubuntu_weather_app
314-
315- to list all tests:
316- $ autopilot3 list ubuntu_weather_app
317-
318- To run only one test (for instance: ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button)
319- $ autopilot3 run -vv ubuntu_weather_app.tests.test_empty_state.TestEmptyState.test_add_location_button
320-
321- Debugging tests using autopilot vis
322- $ autopilot3 launch -i Qt qmlscene app/ubuntu-weather-app.qml
323- $ autopilot3 vis
324-
325-
326-## Running tests on device or emulator:
327-
328-Using autopkg:
329-
330-* Branch the Weather app code, for example,
331- $ bzr branch lp:ubuntu-weather-app
332-
333-* Navigate to the source directory.
334- $ cd ubuntu-weather-app
335-
336-* Build a click package
337- $ click-buddy .
338-
339-* Run the tests on device (assumes only one click package in the directory)
340- $ adt-run . *.click --- ssh -s adb -- -p <PASSWORD>
341
342=== added file 'README.md'
343--- README.md 1970-01-01 00:00:00 +0000
344+++ README.md 2015-12-21 12:54:41 +0000
345@@ -0,0 +1,34 @@
346+ReadMe - Ubuntu Weather App
347+===========================
348+Ubuntu Weather App is the official weather app for Ubuntu Touch. We follow an open
349+source model where the code is available to anyone to branch and hack on. The
350+ubuntu weather app follows a test driven development (TDD) where tests are
351+written in parallel to feature implementation to help spot regressions easier.
352+
353+API
354+===
355+The OpenWeatherMap service requires an API key.
356+Visit [Open Weather](http://openweathermap.org/appid) to obtain a personal key.
357+Click [here](http://openweathermap.org/faq#error401) for more details.
358+Place the key between the quotation marks for the "owmKey" variable in app/data/keys.js
359+
360+**Do not commit branches with the key in place as a centrally managed key is injected at build time.**
361+
362+Dependencies
363+============
364+**DEPENDENCIES ARE NEEDED TO BE INSTALLED TO BUILD AND RUN THE APP**.
365+
366+A complete list of dependencies for the project can be found in ubuntu-weather-app/debian/control
367+
368+The following essential packages are also required to develop this app:
369+* [ubuntu-sdk](http://developer.ubuntu.com/start)
370+* intltool - run `sudo apt-get install intltool`
371+
372+Useful Links
373+============
374+Here are some useful links with regards to the Weather App development.
375+
376+* [Home Page](https://developer.ubuntu.com/en/community/core-apps/weather/)
377+* [Weather App Wiki](https://wiki.ubuntu.com/Touch/CoreApps/Weather)
378+* [Designs](https://developer.ubuntu.com/en/community/core-apps/weather/#design)
379+* [Project page](https://launchpad.net/ubuntu-weather-app)
380
381=== removed file 'README.translations'
382--- README.translations 2015-05-14 23:34:48 +0000
383+++ README.translations 1970-01-01 00:00:00 +0000
384@@ -1,37 +0,0 @@
385-# Updating translations
386-
387-Translations for the Weather app happen in [Launchpad Translations][] and
388-are automatically committed daily on the trunk branch in the po/ folder.
389-
390-They are then built and installed as part of the package build, so that
391-developers don't really need to worry about them.
392-
393-However, there is one task that needs to be taken care of: exposing new
394-translatable messages to translators. So whenever you add new translatable
395-messages in the code, make sure to follow these steps:
396-
397- 1. Run click-buddy to build the project and generate a new .pot file:
398- `click-buddy --dir .`
399- 2. Commit the generated .pot file:
400- `bzr commit -m"Updated translation template"`
401- 3. Push the branch and send a merge proposal as usual
402-
403-And that's it, once the branch lands Launchpad should take care of all the rest!
404-
405-# Behind the scenes
406-
407-Behind the scenes, whenever the po/*.pot file (also known as translations template)
408-is committed to trunk Launchpad reads it and updates the translatable strings
409-exposed in the web UI. This will enable translators to work on the new strings.
410-The translations template contains all translatable strings that have been
411-extracted from the source code files.
412-
413-Launchpad will then store translations in its database and will commit them daily
414-in the form of textual po/*.po files to trunk. The PO files are also usually
415-referred to as the translations files. You'll find a translation file for each
416-language the app has got at least a translated message available for.
417-
418-Translations for core apps follow the standard [gettext format].
419-
420- [Launchpad Translations]: https://translations.launchpad.net/ubuntu-weather-app
421- [gettext format]: https://www.gnu.org/software/gettext/
422
423=== modified file 'debian/changelog'
424--- debian/changelog 2015-12-03 15:22:45 +0000
425+++ debian/changelog 2015-12-21 12:54:41 +0000
426@@ -1,7 +1,11 @@
427 ubuntu-weather-app (3.2) UNRELEASED; urgency=medium
428
429+ [ Andrew Hayzen ]
430 * Release 3.1 and bump version to 3.2
431
432+ [ Girish Rawat ]
433+ * Added new READMEs
434+
435 -- Andrew Hayzen <ahayzen@gmail.com> Thu, 03 Dec 2015 15:20:49 +0000
436
437 ubuntu-weather-app (3.1ubuntu1) vivid; urgency=medium

Subscribers

People subscribed via source and target branches

to all changes: