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

[Girish]

Updated and expanded READMEs.

Improved READMEs.

[Arto Jalkanen (ajalkane)]

Thank you!

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-filemanager-app/READMEs/+merge/281007/+edit-commit-message

review: Needs Fixing (continuous-integration)

[Girish (emailgirishrawat)]

Arto: Have added a commit message. CAn you approve this again?

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

review: Approve (continuous-integration)

=== removed file 'README'
--- README	2014-11-11 19:20:57 +0000
+++ README	1970-01-01 00:00:00 +0000
@@ -1,169 +0,0 @@
-# Ubuntu File Manager
-
-File manager app for Ubuntu on the desktop and on mobile devices.
-
-## Building the app
-
-### For the desktop
-
-Install the following build dependencies:
-
-    sudo apt-get install libtag1-dev libpam0g-dev python3
-
-Then open the CMakeLists.txt file in Qt Creator, and ensure that the kit
-selected on the left sidebar (just above the green "Run" button) is "Desktop"
-
-### For a device
-
-If you don't have one already, you'll need to create an armhf chroot to
-cross-compile the app (also do this if you have an older armhf chroot, for
-example 14.04 and current target is 14.10. You can first delete the old target
-and then create a current one). Here's how:
-
-1. In Qt Creator, open the CMakeLists.txt file
-2. Go to Tools > Options > Ubuntu > Click
-2. Click on Create Click Target
-3. Follow the prompts to generate the chroot. You will be asked for your sudo
-   password
-4. Once created, you'll need to add the build dependencies for the app:
-  - Click on the Maintain button on your chroot
-  - On the terminal prompt that is started, type
-    apt-get install libtag1-dev:armhf libpam0g-dev:armhf python3
-  - Close the terminal when the installation finishes
-5. Now you can either do a clean checkout and wait to be prompted by Qt Creator
-   to add the armhf kit, or alternatively:
-6. Go to the Projects tab > Add kit and then select the UbuntuSDK armhf kit
-
-Additionally, you'll have to tell Qt Creator that you are doing a build for a
-device to ultimately create a click package for installation:
-
-1. In Qt Creator, go to the Projects tab on the sidebar
-2. Click on the "Build" subtab of the "UbuntuSDK for armhf..." tab
-3. Then go to the "CMake arguments" text field and add "-DCLICK_MODE=on"
-   without the quotes
-
-Before starting the build make sure to select the "UbuntuSDK" kit on Qt
-Creator's left sidebar (just above the green "Run" button).
-
-### Doing the build
-
-Ensure you've selected the kit you want for your build and press the build
-button on Qt Creator's left sidebar (or alternatively Ctrl+B).
-
-## Running the app
-
-### On the desktop
-
-No additional steps are required before running the app on the desktop.
-
-You can pass two switches to run in phone or tablet mode from the desktop:
-
--p for phone mode
--t for tablet mode
-
-
-### On a device
-
-Due to Qt Creator's bug #1312094 in launchpad.net, there needs to be a manual
-workaround done before the app can run on the device:
-
-1. Modify the desktop.in file: change the Exec line to read:
-   Exec=lib/arm-linux-gnueabihf/bin/@EXEC@
-
-Remember to revert this temporary change if you are building a click package or
-if you're making other changes to be committed to the code!
-
-### Starting the app
-
-Ensure you've selected the kit you want for your build and press the run
-button on Qt Creator's left sidebar (or alternatively Ctrl+R).
-
-If the app hasn't been built yet, or if there are pending changes that require
-a build, the app will automatically be built first before running.
-
-If you're starting the app on a device, the build will be copied over and the
-code will run unconfined.
-
-## Building a click package
-
-There are two alternative ways of building a click package.
-
-### Using Qt Creator
-
-1. Ensure you've selected the UbuntuSDK for armhf kit on Qt Creator's sidebar
-2. Click on Publish on the sidebar
-3. Click on "Create package"
-4. If all goes well, you'll find the final click package in the build directory
-
-Notes:
-- You can see the output of the click build if you click on Edit on the sidebar
-  and then "Application Output" at the bottom. This is useful to identify any
-  failures during the build
-- Run `sudo apt-get install click-reviewers-tools` to enable click package
-  validation in Qt Creator. You might need to restart Qt Creator after you've
-  installed them for it to detect them
-
-### Using click-buddy
-
-1. Install phablet-tools: `sudo apt-get install phablet-tools`
-2. Run click-buddy in your source tree:
-   click-buddy --dir . --arch armhf --framework ubuntu-sdk-14.04
-3. Once finished, click-buddy will tell you the location of your source package
-
-## Installing a click package
-
-First of all, ensure you've got a working Ubuntu device attached over USB to
-your host computer
-
-### Manually
-
-Run the following commands to manually install the click package (replace 0.5
-with the version of your package):
-
-    adb push com.ubuntu.filemanager_0.3.latest_armhf.click /home/phablet/
-    adb shell
-    sudo -H -u phablet pkcon install-local /home/phablet/com.ubuntu.filemanager_0.3_armhf.click
-
-### Using click-buddy
-
-You can add the --provision argument to the previous command to install the
-click package on the device.
-
-### Starting the app
-
-1. Either kill unity8 with `pkill unity8` or restart the system for the Apps
-   (click) scope to pick up your newly installed click package
-2. Search for Reminders in the Apps scope and tap on its icon to start it
-3. You'll find the runtime logs at ~/.cache/upstart/application-click/
-
-## Uninstalling a click package
-
-Run the following commands, replacing the version of the click package you want
-to uninstall:
-
-    adb shell
-    sudo -iu phablet
-    sudo click unregister com.ubuntu.filemanager 0.3
-
-## Run the autopilot tests
-
-Prerequisites:
-    sudo apt-get install ubuntu-ui-toolkit-autopilot
-
-Once the app has been built, you can go to the build directory and run:
-
-    cd tests/autopilot
-    autopilot3 run filemanager
-
-You can run filemanager in phone or tablet mode passing one of these two switches:
-
--p for phone mode
--t for tablet mode
-
-so:
-
-autopilot3 launch ../../src/app/filemanager -p
-
-will launch filemanager with autopilot in phone mode.
-
-
 
=== added file 'README-Autopilot.md'
--- README-Autopilot.md	1970-01-01 00:00:00 +0000
+++ README-Autopilot.md	2015-12-19 07:36:54 +0000
@@ -0,0 +1,19 @@
+ReadMe - Run Autopilot tests
+============================
+
+# Prerequisites
+* ubuntu-ui-toolkit-autopilot : sudo apt-get install ubuntu-ui-toolkit-autopilot
+
+# Next Steps
+Once the app has been built, you can go to the build directory and run:
+
+    cd tests/autopilot
+    autopilot3 run filemanager
+
+You can run filemanager in phone or tablet mode passing one of these two switches:
+
+-p for phone mode
+-t for tablet mode
+
+* autopilot3 launch ../../src/app/filemanager -p will launch filemanager with autopilot in phone mode
+* autopilot3 launch ../../src/app/filemanager -t will launch filemanager with autopilot in tablet mode.
 
=== added file 'README-ContentHubDesktop.md'
--- README-ContentHubDesktop.md	1970-01-01 00:00:00 +0000
+++ README-ContentHubDesktop.md	2015-12-19 07:36:54 +0000
@@ -0,0 +1,63 @@
+Testing Content-Hub support
+===========================
+
+## For the desktop
+
+Install the following dependencies to run click applications:
+
+    sudo apt-get install upstart-app-launch-tools
+
+### Build FileManager and install FileManager as click package
+
+Build FileManager as a click package and install it. At the time of this writing
+this doesn't seem to be working with the SDK (due to cmake), but it can be done 
+from command line:
+
+First you must modify manifest.json and replace "architecture" value of "armhf" with "i386".
+Just remember to change it back to armhf if you commit changes.
+
+After that you can build x86 version of the package and install it:
+
+    QT_SELECT=qt5 cmake . -DCLICK_MODE=1 && make -j2 && make install DESTDIR=install && click build install
+    sudo click install --user=$USER ./com.ubuntu.filemanager_0.3.latest_i386.click 
+
+### Build and install hub-importer as click package
+
+Get the sources for building:
+
+    bzr branch lp:~ken-vandine/+junk/hub-importer
+
+You should be able to create click package out of it in SDK by opening the project and using Publish and Create package.
+
+Install the created package (example):
+
+    sudo click install --user=$USER com.ubuntu.developer.ken-vandine.hub-importer_0.2_all.click
+
+### Running test
+
+Run hub-importer (example):
+
+    upstart-app-launch com.ubuntu.developer.ken-vandine.hub-importer_hub-importer_0.2
+
+Click "Select source" button.
+
+You should see File Manager as one of the choices. If you do not see File Manager, look at "Troubleshooting" section.
+Click on File Manager, and File Manager should start. Now you should choose some pictures as that's the only thing
+supported at the moment (even though FileManager allows selecting any type). You can select multiple files in a 
+directory if you so choose. Once you're satisfied with the seelction, click "Select". You should see the pictures 
+then in Hub Importer.
+
+Troubleshooting
+===============
+
+* If you don't see File Manager as one of the choises in Hub Importer, then quit Hub Importer and run this script:
+    /usr/lib/i386-linux-gnu/content-hub/content-hub-peer-hook
+   Try running Hub Importer again after that and File Manager should show.
+   If the above script does not exist, you can try locating something similar with:
+    locate hook
+* If you have trouble running Hub Importer or the above still doesn't work, check the installed click packages with:
+   click list
+   It should show entry for both File Manager and Hub Importer. If it does not, installing the click package has not succeeded
+* If all else fails, check the logs for both Hub Importer and File Manager for further clues at:
+    $HOME/.cache/upstart/
+
 
=== added file 'README-Developers.md'
--- README-Developers.md	1970-01-01 00:00:00 +0000
+++ README-Developers.md	2015-12-19 07:36:54 +0000
@@ -0,0 +1,151 @@
+Building the app
+================
+
+### For the desktop
+
+Install the following build dependencies:
+
+    sudo apt-get install libtag1-dev libpam0g-dev python3
+
+Then open the CMakeLists.txt file in Qt Creator, and ensure that the kit
+selected on the left sidebar (just above the green "Run" button) is "Desktop"
+
+### For a device
+
+If you don't have one already, you'll need to create an armhf chroot to
+cross-compile the app (also do this if you have an older armhf chroot, for
+example 14.04 and current target is 14.10. You can first delete the old target
+and then create a current one). Here's how:
+
+1. In Qt Creator, open the CMakeLists.txt file
+2. Go to Tools > Options > Ubuntu > Click
+2. Click on Create Click Target
+3. Follow the prompts to generate the chroot. You will be asked for your sudo
+   password
+4. Once created, you'll need to add the build dependencies for the app:
+  - Click on the Maintain button on your chroot
+  - On the terminal prompt that is started, type
+    apt-get install libtag1-dev:armhf libpam0g-dev:armhf python3
+  - Close the terminal when the installation finishes
+5. Now you can either do a clean checkout and wait to be prompted by Qt Creator
+   to add the armhf kit, or alternatively:
+6. Go to the Projects tab > Add kit and then select the UbuntuSDK armhf kit
+
+Additionally, you'll have to tell Qt Creator that you are doing a build for a
+device to ultimately create a click package for installation:
+
+1. In Qt Creator, go to the Projects tab on the sidebar
+2. Click on the "Build" subtab of the "UbuntuSDK for armhf..." tab
+3. Then go to the "CMake arguments" text field and add "-DCLICK_MODE=on"
+   without the quotes
+
+Before starting the build make sure to select the "UbuntuSDK" kit on Qt
+Creator's left sidebar (just above the green "Run" button).
+
+### Doing the build
+
+Ensure you've selected the kit you want for your build and press the build
+button on Qt Creator's left sidebar (or alternatively Ctrl+B).
+
+
+Running the app
+===============
+
+### On the desktop
+
+No additional steps are required before running the app on the desktop.
+
+You can pass two switches to run in phone or tablet mode from the desktop:
+
+-p for phone mode
+-t for tablet mode
+
+
+### On a device
+
+Due to Qt Creator's bug #1312094 in launchpad.net, there needs to be a manual
+workaround done before the app can run on the device:
+
+1. Modify the desktop.in file: change the Exec line to read:
+   Exec=lib/arm-linux-gnueabihf/bin/@EXEC@
+
+Remember to revert this temporary change if you are building a click package or
+if you're making other changes to be committed to the code!
+
+### Starting the app
+
+Ensure you've selected the kit you want for your build and press the run
+button on Qt Creator's left sidebar (or alternatively Ctrl+R).
+
+If the app hasn't been built yet, or if there are pending changes that require
+a build, the app will automatically be built first before running.
+
+If you're starting the app on a device, the build will be copied over and the
+code will run unconfined.
+
+
+Building a click package
+========================
+
+There are two alternative ways of building a click package.
+
+### Using Qt Creator
+
+1. Ensure you've selected the UbuntuSDK for armhf kit on Qt Creator's sidebar
+2. Click on Publish on the sidebar
+3. Click on "Create package"
+4. If all goes well, you'll find the final click package in the build directory
+
+Notes:
+- You can see the output of the click build if you click on Edit on the sidebar
+  and then "Application Output" at the bottom. This is useful to identify any
+  failures during the build
+- Run `sudo apt-get install click-reviewers-tools` to enable click package
+  validation in Qt Creator. You might need to restart Qt Creator after you've
+  installed them for it to detect them
+
+### Using click-buddy
+
+1. Install phablet-tools: `sudo apt-get install phablet-tools`
+2. Run click-buddy in your source tree:
+   click-buddy --dir . --arch armhf --framework ubuntu-sdk-14.04
+3. Once finished, click-buddy will tell you the location of your source package
+
+
+Installing a click package
+==========================
+
+First of all, ensure you've got a working Ubuntu device attached over USB to
+your host computer
+
+### Manually
+
+Run the following commands to manually install the click package (replace 0.5
+with the version of your package):
+
+    adb push com.ubuntu.filemanager_0.3.latest_armhf.click /home/phablet/
+    adb shell
+    sudo -H -u phablet pkcon install-local /home/phablet/com.ubuntu.filemanager_0.3_armhf.click
+
+### Using click-buddy
+
+You can add the --provision argument to the previous command to install the
+click package on the device.
+
+### Starting the app
+
+1. Either kill unity8 with `pkill unity8` or restart the system for the Apps
+   (click) scope to pick up your newly installed click package
+2. Search for Reminders in the Apps scope and tap on its icon to start it
+3. You'll find the runtime logs at ~/.cache/upstart/application-click/
+
+
+Uninstalling a click package
+============================
+
+Run the following commands, replacing the version of the click package you want
+to uninstall:
+
+    adb shell
+    sudo -iu phablet
+    sudo click unregister com.ubuntu.filemanager 0.3
 
=== added file 'README-Mergeproposal'
--- README-Mergeproposal	1970-01-01 00:00:00 +0000
+++ README-Mergeproposal	2015-12-19 07:36:54 +0000
@@ -0,0 +1,28 @@
+Prerequisites to approving a Merge Proposal (MP)
+================================================
+
+Over time, it has been found that insufficient testing by reviewers sometimes leads to file manager 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 file manager 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 file manager 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-19 07:36:54 +0000
@@ -0,0 +1,38 @@
+Updating translations
+=====================
+
+Translations for the Filemanager app happen in [Launchpad Translations](https://translations.launchpad.net/ubuntu-filemanager-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-filemanager-app)
+ [gettext format](https://www.gnu.org/software/gettext/)
 
=== removed file 'README.contentHubDesktop'
--- README.contentHubDesktop	2014-07-01 21:55:07 +0000
+++ README.contentHubDesktop	1970-01-01 00:00:00 +0000
@@ -1,65 +0,0 @@
-# Ubuntu File Manager
-
-File manager app for Ubuntu on the desktop and on mobile devices.
-
-## Testing Content-Hub support
-
-### For the desktop
-
-Install the following dependencies to run click applications:
-
-    sudo apt-get install upstart-app-launch-tools
-
-#### Build FileManager and install FileManager as click package
-
-Build FileManager as a click package and install it. At the time of this writing
-this doesn't seem to be working with the SDK (due to cmake), but it can be done 
-from command line:
-
-First you must modify manifest.json and replace "architecture" value of "armhf" with "i386".
-Just remember to change it back to armhf if you commit changes.
-
-After that you can build x86 version of the package and install it:
-
-    QT_SELECT=qt5 cmake . -DCLICK_MODE=1 && make -j2 && make install DESTDIR=install && click build install
-    sudo click install --user=$USER ./com.ubuntu.filemanager_0.3.latest_i386.click 
-
-#### Build and install hub-importer as click package
-
-Get the sources for building:
-
-    bzr branch lp:~ken-vandine/+junk/hub-importer
-
-You should be able to create click package out of it in SDK by opening the project and using Publish and Create package.
-
-Install the created package (example):
-
-    sudo click install --user=$USER com.ubuntu.developer.ken-vandine.hub-importer_0.2_all.click
-
-#### Running test
-
-Run hub-importer (example):
-
-    upstart-app-launch com.ubuntu.developer.ken-vandine.hub-importer_hub-importer_0.2
-
-Click "Select source" button.
-
-You should see File Manager as one of the choices. If you do not see File Manager, look at "Troubleshooting" section.
-Click on File Manager, and File Manager should start. Now you should choose some pictures as that's the only thing
-supported at the moment (even though FileManager allows selecting any type). You can select multiple files in a 
-directory if you so choose. Once you're satisfied with the seelction, click "Select". You should see the pictures 
-then in Hub Importer.
-
-#### Troubleshooting
-
- - If you don't see File Manager as one of the choises in Hub Importer, then quit Hub Importer and run this script:
-    /usr/lib/i386-linux-gnu/content-hub/content-hub-peer-hook
-   Try running Hub Importer again after that and File Manager should show.
-   If the above script does not exist, you can try locating something similar with:
-    locate hook
- - If you have trouble running Hub Importer or the above still doesn't work, check the installed click packages with:
-   click list
-   It should show entry for both File Manager and Hub Importer. If it does not, installing the click package has not succeeded
- - If all else fails, check the logs for both Hub Importer and File Manager for further clues at:
-    $HOME/.cache/upstart/
-
 
=== added file 'README.md'
--- README.md	1970-01-01 00:00:00 +0000
+++ README.md	2015-12-19 07:36:54 +0000
@@ -0,0 +1,26 @@
+ReadMe - Ubuntu File Manager
+============================
+
+Ubuntu File Manager App is the official file manager app for Ubuntu Touch. We follow an open
+source model where the code is available to anyone to branch and hack on. The
+ubuntu file manager app follows a test driven development (TDD) where tests are
+written in parallel to feature implementation to help spot regressions easier.
+
+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 filemanager-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 File Manager App development.
+
+* [Home Page](https://developer.ubuntu.com/en/community/core-apps/file-manager/)
+* [File Manager App Wiki](https://wiki.ubuntu.com/Touch/CoreApps/FileManager)
+* [Project page](https://launchpad.net/ubuntu-filemanager-app) 
+
 
=== removed file 'README.translations'
--- README.translations	2014-08-16 07:04:04 +0000
+++ README.translations	1970-01-01 00:00:00 +0000
@@ -1,36 +0,0 @@
-# Updating translations
-
-Translations for the Filemanager 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-filemanager-app
- [gettext format]: https://www.gnu.org/software/gettext/
 
=== modified file 'debian/changelog'
--- debian/changelog	2015-06-26 18:59:37 +0000
+++ debian/changelog	2015-12-19 07:36:54 +0000
@@ -1,3 +1,9 @@
+ubuntu-filemanager-app (0.4ubuntu1) UNRELEASED; urgency=medium
+
+  * Improved READMEs
+
+ -- Girish Rawat <[e-mail]>  Sat, 19 Dec 2015 13:03:56 +0530
+
 ubuntu-filemanager-app (0.4) wily; urgency=medium
 
   * Renamed PAM module to not conflict with the Terminal one.