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

[Girish]

Updated and expanded READMEs.

Updated and expanded READMEs.

[Stefano Verzegnassi (verzegnassi-stefano)]

Hi,

Thanks for this big improvement!

I had a look at your MP and overall it looks very good.
However, some minor change is required in order to reflect the current status of the project.

* Some of the Autopilot tests are currently broken.
  It may be worth to point that out in the 'README-Mergeproposal.md' file, explaining that they aren't strictly required at the moment. The same goes for 'README-Autopilot.md' file.

* In the 'README-Developers.md' file, we mention that LibreOffice 5.0 is not available in the archive. This is no longer true, since it's available in Ubuntu 15.10 archives.
  For earlier release, we may want to refer to the following PPA, which includes only stable releases:
     ppa:libreoffice/libreoffice-5-0

* Still in the same file, in the 'Compiling" section, it may be useful to specify that a working internet connection is required in order to build the project, since a number of Debian packages are downloaded when the project is loaded the first time through (e.g.) QtCreator.

* Still a small correction to 'README-Mergeproposal'.
  The line:
    "Does the MP change the UI? If Yes, has it been approved by design?"
  does not reflect our current workflow, since a large part of the UI hasn't been approved by the design team (it has been approved by the devs instead).
  Please replace that line with:
    "Does the MP change the UI? If Yes, has it been approved by design, or discussed with some of the DocViewer developers?"

Thanks again!

review: Needs Fixing

[lp:~emailgirishrawat/ubuntu-docviewer-app/READMEs]

236. By Girish on 2015-12-21

Updated READMEs

[Girish (emailgirishrawat)]

Fixed.

[Stefano Verzegnassi (verzegnassi-stefano)]

LGTM. Good job, thanks!

review: Approve

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

review: Approve (continuous-integration)

=== removed file 'README'
--- README	2015-06-29 08:51:39 +0000
+++ README	1970-01-01 00:00:00 +0000
@@ -1,39 +0,0 @@
-Usage
-=====
-ubuntu-docviewer-app [filename]
-
-filename : The path where the file you want to open is located.
-
-Compiling
-=========
-
-Install poppler's development files:
-    sudo apt install libpoppler-qt5-dev
-
-Install Qt5 private development files:
-    sudo apt install qtdeclarative5-private-dev qtbase5-private-dev
-
-If you want to compile an arm click package, you need to install that package
-to the arm compilation environment. For example when using QtCreator for
-Ubuntu Touch, open Options -> Ubuntu -> Maintain, and then enter:
-
-    apt install libpoppler-qt5-dev:armhf qtdeclarative5-private-dev:armhf qtbase5-private-dev:armhf
-
-LibreOffice viewer support
-==========================
-
-If you want to enable the LibreOffice viewer feature, you'll need to have a
-LibreOffice 5.0 installation on your development environment. At the time of
-writing, LibreOffice 5.0 is not yet in the archive, but you can easily install
-it from the pre-releases PPA. To do so, type the following commands on a
-terminal:
-
-    sudo apt-get purge libreoffice-core
-    sudo add-apt-repository ppa:libreoffice/libreoffice-prereleases
-    sudo apt-get update
-    sudo apt-get install libreoffice
-
-Then to compile the LibreOffice viewer plugin you'll simply need to install
-the LibreOffice Kit development files:
-
-    sudo apt install libreofficekit-dev

=== added file 'README-Autopilot.md'
--- README-Autopilot.md	1970-01-01 00:00:00 +0000
+++ README-Autopilot.md	2015-12-21 13:07:23 +0000
@@ -0,0 +1,81 @@
+Running Autopilot tests
+=======================
+
+As of wily 15.10, some autopilot tests are broken in trunk. As such autopilot failures
+can be excused until they are fixed in trunk.
+
+The Doc Viewer 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 Doc Viewer 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 doc viewer app, here are some useful links to help you:
+
+- [Ubuntu - Quality](http://developer.ubuntu.com/start/quality)
+- [Autopilot - Python](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 Doc Viewer app code, for example,
+
+    $ bzr branch lp:ubuntu-docviewer-app
+    
+*  Navigate to the tests/autopilot directory.
+
+    $ cd ubuntu-docviewer-app/tests/autopilot
+
+*  run all tests.
+
+    $ autopilot3 run -vv ubuntu_docviewer_app
+
+* to list all tests:
+
+    $ autopilot3 list ubuntu_docviewer_app
+
+ To run only one test (for instance: ubuntu_docviewer_app.tests.test_docviewer.TestMainWindow.test_open_pdf_file)
+
+
+    $ autopilot3 run -vv ubuntu_docviewer_app.tests.test_docviewer.TestMainWindow.test_open_pdf_file
+
+* Debugging tests using autopilot vis
+
+    $ autopilot3 launch -i Qt qmlscene app/ubuntu-docviewer-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 Doc Viewer app code, for example,
+
+    $ bzr branch lp:ubuntu-docviewer-app
+
+*  Navigate to the source directory.
+
+    $ cd ubuntu-docviewer-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 13:07:23 +0000
@@ -0,0 +1,43 @@
+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-docviewer-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` 
+
+Compiling
+=========
+
+**A working internet connection is required in order to build the project. A number of Debian packages are downloaded when the project is loaded the first times**
+
+* Install poppler's development files:
+    sudo apt install libpoppler-qt5-dev
+
+* Install Qt5 private development files:
+    sudo apt install qtdeclarative5-private-dev qtbase5-private-dev
+
+* If you want to compile an arm click package, you need to install that package
+  to the arm compilation environment. For example when using QtCreator for
+  Ubuntu Touch, open Options -> Ubuntu -> Maintain, and then enter:
+
+    apt install libpoppler-qt5-dev:armhf qtdeclarative5-private-dev:armhf qtbase5-private-dev:armhf
+
+LibreOffice viewer support
+==========================
+
+* If you want to enable the LibreOffice viewer feature, you'll need to have a
+  LibreOffice 5.0 installation on your development environment. 
+  To do so, type the following commands on a terminal:
+
+    sudo apt-get purge libreoffice-core
+    sudo add-apt-repository ppa:libreoffice/libreoffice-5-0
+    sudo apt-get update
+    sudo apt-get install libreoffice
+
+* Then to compile the LibreOffice viewer plugin you'll simply need to install
+  the LibreOffice Kit development files:
+
+    sudo apt install libreofficekit-dev

=== added file 'README-Mergeproposal.md'
--- README-Mergeproposal.md	1970-01-01 00:00:00 +0000
+++ README-Mergeproposal.md	2015-12-21 13:07:23 +0000
@@ -0,0 +1,32 @@
+Prerequisites to approving a Merge Proposal (MP)
+================================================
+
+Over time, it has been found that insufficient testing by reviewers sometimes leads to doc viewer 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, or 
+    discussed with some of the DocViewer developers?
+
+*   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 doc viewer 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 doc viewer app trunk stay buildable,
+stable and up to date.
+
+Note: As of wily 15.10, some autopilot tests are broken in trunk. As such autopilot failures
+can be excused until they are fixed in trunk.
+

=== added file 'README-Translations.md'
--- README-Translations.md	1970-01-01 00:00:00 +0000
+++ README-Translations.md	2015-12-21 13:07:23 +0000
@@ -0,0 +1,37 @@
+Updating translations
+=====================
+
+Translations for the Document Viewer app happen in [Launchpad Translations](https://translations.launchpad.net/ubuntu-docviewer-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 retaining the build directory:
+    `click-buddy --dir . --no-clean`
+ 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-docviewer-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-21 13:07:23 +0000
@@ -0,0 +1,30 @@
+ReadMe - Ubuntu Doc Viewer App
+==============================
+Ubuntu Doc Viewer App is the official document viewer app for Ubuntu Touch. We follow an open
+source model where the code is available to anyone to branch and hack on. The
+ubuntu doc viewer app follows a test driven development (TDD) where tests are
+written in parallel to feature implementation to help spot regressions easier.
+
+Usage
+=====
+ubuntu-docviewer-app [filename]
+
+filename : The path where the file you want to open is located.
+
+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-docviewer-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 Doc Viewer App development.
+
+* [Home Page](https://developer.ubuntu.com/en/community/core-apps/docviewer/)
+* [Doc Viewer App Wiki](https://wiki.ubuntu.com/Touch/CoreApps/DocViewer)
+* [Project page](https://launchpad.net/ubuntu-docviewer-app) 

=== removed file 'README.translations'
--- README.translations	2015-01-24 00:03:13 +0000
+++ README.translations	1970-01-01 00:00:00 +0000
@@ -1,36 +0,0 @@
-# Updating translations
-
-Translations for the Document Viewer 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 retaining the build directory:
-    `click-buddy --dir . --no-clean`
- 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-docviewer-app
- [gettext format]: https://www.gnu.org/software/gettext/

=== modified file 'debian/changelog'
--- debian/changelog	2015-12-02 15:14:33 +0000
+++ debian/changelog	2015-12-21 13:07:23 +0000
@@ -1,3 +1,9 @@
+ubuntu-docviewer-app (2.0ubuntu1) UNRELEASED; urgency=medium
+
+  * Updated and expanded READMEs
+
+ -- Girish Rawat <[e-mail]>  Sun, 20 Dec 2015 01:23:18 +0530
+
 ubuntu-docviewer-app (2.0) vivid; urgency=medium
 
   * Updated application icon (LP: #1476659 and LP: #1432392)