* Add basic documentation

* Improve project description paragraphs for added clarity and simplicity

* Add link to learn more about Digital Skills Observatory

* Simplify installation instructions

* Add link to chat.mozillafoundation.org in Contribute section

* Fix contribute section not actually linking to contributing guide

* Derp :bowtie

* Improve contribute descriptions for added clarity and simplicity

* Clean up terminology table and language

* Add logo and revise contribute layout

* Remove old documentation folder, Update image path

* Remove old dso app wireframes

* Fix logo not displaying, See isaacs/github#316

* Fix file not actually being converted to a png

* Add USB Debugging & App Setup instructions to documentation

* Minor style tweaks, clean up a bit

* Add Android Studio installation documentation

* Remove manual install guide for android sdk

* Fix broken contributing guide link in readme

* Add mofo engineering guidebook to contribute table of contents

* Add detailed install instructions to README

* Add MoFo Engineering Standards segment to contribute guide

* Add building information to contribute guide

* Some formatting changes to build type stuff

* Custom guide
This commit is contained in:
Ryan 2017-01-02 18:35:56 -05:00 коммит произвёл GitHub
Родитель f314fb5eba
Коммит 2589025ae6
11 изменённых файлов: 200 добавлений и 13011 удалений

24
CODE_OF_CONDUCT.md Normal file
Просмотреть файл

@ -0,0 +1,24 @@
# Participation Guidelines
This project respects Mozilla's [community participation guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). These guidelines cover our behaviour as participants, facilitators, space wranglers, staff, volunteers, vendors, and anyone else involved in making the MozFest possible.
## How to treat each other
* Be respectful and welcoming
* Try to understand different perspectives
* Do not threaten violence
* Empower others
* Strive for excellence
* Dont expect to agree with every decision
## Inclusion and Diversity
The Mozilla Project welcomes and encourages participation by everyone. It doesnt matter how you identify yourself or how others perceive you: we welcome you.
We welcome contributions from everyone as long as they interact constructively with our community, including, but not limited to people of varied age, culture, ethnicity, gender, gender-identity, language, race, sexual orientation, geographical location and religious views.
Mozilla-based activities should be inclusive and should support such diversity.
## Working in the Open
Because working open is one of our core values, MozFest program planning is done in the open on Github (check out our repo [here](https://github.com/MozillaFoundation/mozfest-program-2016)). We hope participants will benefit from this culture of transparency and collaboration during the Festival, and will continue to work with an open ethos in their projects after Mozfest. Learn more about [how we work open at Mozilla](https://wiki.mozilla.org/Working_open).

Просмотреть файл

@ -1,22 +0,0 @@
### Contributors
* Festus Langat ([@festolangat](https://github.com/festolangat))
* Dobbz Mkolwe ([@dobbz](https://github.com/dobbz))
* Brian Mwadime ([@brianmwadime](https://github.com/brianmwadime))
* Walter (Loso) Obadha ([@obadha](https://github.com/obadha))
* Bonface Ochieng ([@TheBonface](https://github.com/TheBonface))
* Mike Otieno ([@icarius06](https://github.com/icarius06))
* Luke Pacholski ([@flukeout](https://github.com/flukeout))
* Laura de Reynal ([@laurareynal](https://github.com/laurareynal))
* Bobby Richter ([@secretrobotron](https://github.com/secretrobotron))
* Chad Sansing ([@chadsansing](https://github.com/chadsansing))
* Alex Wafula ([@xelawafs](https://github.com/xelawafs))
* Stephen Wanjau ([@Uwanja](https://github.com/Uwanja))
... and the rest of the [DSO Community](http://mzl.la/dso).
### Tutorial Images
* `"Goat" Created by Hernan D. Schlosman from the Noun Project`
* `"Gorilla" Created by Hernan D. Schlosman from the Noun Project`
* `"Elephant" Created by Created by Sebastian Andreasson from the Noun Project`

Просмотреть файл

@ -1,27 +1,37 @@
Mozilla DSO Android App
======================
# Jisort! [![Build Status](https://travis-ci.org/mozilla/Jisort.svg?branch=master)](https://travis-ci.org/mozilla/Jisort) [![Uses Mofo Standards](https://MozillaFoundation.github.io/mofo-standards/badge.svg)](https://github.com/MozillaFoundation/mofo-standards)
Description goes here..
Jisort! is an informational prototype app for the Digital Skills Observatory project. It offers fun and visually interesting ways to increase basic smart phone awareness and skills, diagnose problems, and encourage exploration.
<h2>Source</h2>
The Digital Skills Observatory project looks at the impact of digital skills on the usage of Digital Financial Services. Testing various teaching and delivery methods, the study aims to understand the skills people need to develop confidence and agency with their smart phones. [Learn more](http://mozillafoundation.github.io/digital-skills-observatory/).
The source code in this repository reflects the app's current status.
## Features
<h2>Features</h2>
- Compatible with Android 4.0 (API 14) and above
- Simple and intuitive user interface
- Suggest content to users based on system events like low battery, or wifi status
- Customizable: create your own content using HTML tags and JSON
- Offline analytics collection system
With the app, you can:
## Install
- View tutorial content.
- View suggested topics based on system events like low battery; wifi, location or bluetooth status.
- View detailed tutorial content.
- Enable/disable app FAB.
Jisort! is not available on app marketplaces such as Google Play. Follow the instructions below to manually install the app.
<h2>How to Work with the Source</h2>
1. Startup the internet browser on the Android device you'd like to install Jisort! on
2. Enter the following website address into your browser's address bar: ```https://mzl.la/jisort```
3. Look for the version with the green "latest release" tag, and download the file ending with the extension name: ```apk```
4. Navigate to your downloads folder and verify that the downloaded file looks similar to the following: ```Jisort-qualityassurance-<version>-SNAPSHOT.apk```
5. Tap on the downloaded file to begin the installation process
6. If prompted with a pop-up asking if you'd like to install the application, select the appropriate answers (yes)
7. Once the application has been successfully installed, you will be notified and can find it in your app drawer
We hope the source code for this app is useful for you as a reference or starting point for creating your own apps. Here is some additional reading to help you better understand and reuse this code.
## Contribute
* [Build instructions](doc/BUILDING.md): instructions on how to build and run the code.
* [Customization guide](doc/CUSTOM.md)
Did you know that the Digital Skills Observatory project is mostly run by community members just like you? Community contributions have played an important role in both the Digital Skills Observatory project, and the development of Jisort!
<h2>Contributors/Credits</h2>
More contributor information can be found in the [CREDITS.md](CREDITS.md) file.
If you're interested in contributing, check out the [contributing guide](docs/CONTRIBUTE.md) and come say hello in our [chat room](https://chat.mozillafoundation.org).
## License
Jisort! is licensed under [Mozilla Public License 2.0](LICENSE.md)
Have questions about Mozilla Public License 2.0? Check out the [FAQ](https://www.mozilla.org/en-US/MPL/2.0/FAQ/).

Различия файлов скрыты, потому что одна или несколько строк слишком длинны

Просмотреть файл

@ -1,72 +0,0 @@
Copyright 2015 Mozilla Foundation. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
# How to build Mozilla DSO app
This is a Gradle-based project that works best with
[Android Studio](http://developer.android.com/sdk/installing/studio.html)
To build the app:
1. Install the following software:
- Android SDK:
http://developer.android.com/sdk/index.html
- Gradle:
http://www.gradle.org/downloads
- Android Studio:
http://developer.android.com/sdk/installing/studio.html
1. Run the Android SDK Manager by pressing the SDK Manager toolbar button
in Android Studio or by running the 'android' command in a terminal
window.
1. In the Android SDK Manager, ensure that the following are installed,
and are updated to the latest available version:
- Tools > Android SDK Platform-tools
- Tools > Android SDK Tools
- Tools > Android SDK Build-tools
- Android 6.0 > SDK Platform (API 23)
- Extras > Android Support Repository
- Extras > Android Support Library
- Extras > Google Play services
- Extras > Google Repository
1. Create a file in your working directory called local.properties,
containing the path to your Android SDK. Use local.properties.example as a
model.
1. Import the project in Android Studio:
1. Press File > Import Project
1. Navigate to and choose the settings.gradle file in this project
1. Press OK
1. Add your debug keystore to the project (save it as keystore/debug.keystore),
or modify the build.gradle file to point to your key.
1. Choose Build > Make Project in Android Studio or run the following
command in the project root directory:
```
./gradlew clean assembleDebug
```
1. To install on your test device:
```
./gradlew installDebug
```
Done.

Просмотреть файл

@ -1,43 +0,0 @@
Copyright 2014 Mozilla Foundation. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
# Customizing the app for your own data
To customize the app for your own data, you will need to:
1. Set up the build as described
in [BUILDING.md](BUILDING.md)
5. Edit Config.java settings as appropriate for your data
6. Generate bootstrap JSON data (which should be a recent snapshot of the
tutorial data JSON files) and save it to
res/raw/bootstrap_data.json. More information about format in
[SYNC.md](SYNC.md)
7. Modify the app to add your own icons, colors etc.
Here are a few more details about each step.
## Set up Config.java
The Config.java file is located at:
[android/src/main/java/com/mozilla/hackathon/kiboko/Config.java](../android/src/main/java/com/mozilla/hackathon/kiboko/Config.java)
This file controls most of the event-specific aspects of IOSched.
Make sure to edit this file to reflect the configuration you need
for your event. Read the comments on the file for details about
what each configuration parameter means.

Просмотреть файл

@ -1,99 +0,0 @@
Copyright 2014 Mozilla Foundation. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
# Data format
The format of the JSON file is:
```JSON
{
"<entity_collection>": [
<entity>,
<entity>,
<entity>
],
"<entity_collection>": [
<entity>,
<entity>,
<entity>
]
}
```
That is, each file consists of one or more collections of entities,
organized by type. Example entity collections are: tutorials, steps etc.
## Bootstrap data
When the user runs the app for the first time, they expect to see
data. The app ships with preloaded "bootstrap data", which
is essentially a preloaded offline snapshot of the JSON data. This
data is parsed by the app and saved to the database on first execution.
You can find this file in [res/raw/bootstrap_data.json](../android/src/main/res/raw).
## Data format
Below is the documentation about the format of each type of entity
supported by the Mozilla DSO android app.
### Tutorials and steps
```JSON
{
"tutorials": [
<tutorial>,
<tutorial>,
<tutorial>,
...
]
}
```
Where each `<tutorial>` has this format:
```JSON
{
"id": "1",
"tag": "wifi",
"header": "Wi-Fi ni Noma!",
"photoUrl": "url",
"steps": [{
"id": "1",
"title": "What is Wi-Fi?",
"gifUrl": "wifi1",
"description": "Wi-Fi is a technology that helps your phone connect to the internet, similar to airtime or mobile data. However, <b>Wi-Fi doesn't use your airtime or mobile data.</b> Instead, in coffee shops or public spaces, Wi-Fi is often free."
}, {
"id": "2",
"title": "Where do I get it? Who owns it?",
"gifUrl": "wifi2",
"description": "Wi-Fi networks are created by \"hotspots\" that connect to the internet. Anyone can buy one and set it up at home, at work, or in a public space. If you can detect a Wi-Fi network on your phone, you might be able to connect to it. To learn more about connecting, check out Connecting to Wi-Fi."
}, {
"id": "3",
"title": "Saving Money",
"gifUrl": "wifi3",
"description": "Wi-Fi is great for saving money because it lets you connect to the internet without using mobile data or airtime on your phone. Remember, though, sometimes you have to pay a small fee to use Wi-Fi at a business or cafe, or buy some goods."
}, {
"id": "4",
"title": "Speed and Stability",
"gifUrl": "wifi4",
"description": "Wi-Fi networks are generally more stable and faster than mobile data networks. Wi-Fi was designed to support multiple smartphones at once and lots of internet browsing. Downloading files or streaming videos is best over Wi-Fi.\n<b>Be aware:</b> it is not <b>always</b> the case that Wi-Fi is faster and more stable than mobile data. Depending on infrastructure, popularity, and other environmental factors, Wi-Fi may not be as responsive or reliable."
}]
}
```

76
docs/CONTRIBUTE.md Normal file
Просмотреть файл

@ -0,0 +1,76 @@
# Contribute
Mozilla Foundation currently (as of 2016) uses Mattermost as our communications solution. If at any point you need help, have a question or just want to say hello; join our [chat room](https://chat.mozillafoundation.org).
* [Install Android Studio](#install-android-studio)
* The first step of getting set up for Android development is installing Android Studio.
* [USB Debugging](#usb-debugging)
* USB debugging allows you to use your phone in order to test your app changes and debug them if necessary.
* [Setup Jisort App](#setup-jisort-app)
* All the steps needed to get a local version of the Jisort! app repository running locally on your Android phone.
* [Review MoFo Engineering Standards](#review-mofo-engineering-standards)
* Mozilla Foundation's engineering standards is a guide book that details best practices when contributing.
* [Building Jisort App](#building-jisort-app)
* Information on how to build Jisort! as well as a table with all build types and descriptions.
## Install Android Studio
* Verify that you have Java 1.8 and [JDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) installed for your platform
* Download and install Android Studio from: https://developer.android.com/studio/index.html
* After it has installed successfully, you should see the following screen:
![android studio menu](img/android-studio-menu.png)
## USB Debugging
* In order to start testing apps on your physical Android device, we need to first activate developer mode by tapping ```Settings > About > Build Number``` seven times
* Once activated, go to ```Settings > Developer Options > USB Debugging``` and make sure USB Debugging is enabled
* Connect your phone to your computer via USB and select the green "run" button from the Android Studio tool bar or hit ```Run > Run 'app'``` from the menu bar. Your device should show up under the "Connected Devices" tab. If you've installed Android command line tools, you can also verify your phone is connected by running ```adb devices``` from the command line
* [This guide](http://www.howtogeek.com/129728/how-to-access-the-developer-options-menu-and-enable-usb-debugging-on-android-4.2/) has additional information for enabling USB Debugging
## Setup Jisort App
* Clone the Jisort code repository from [mozilla/Jisort](https://github.com/mozilla/Jisort)
* In Android Studio, choose "Open an existing Android project"
* Select the Jisort folder, and press open
* Connect your device via USB, and press the "run" button:
![run button](img/android-run-btn.png)
## Review MoFo Engineering Standards
The Mozilla Foundation engineering standards guidebook outlines the best practices used by Mozilla Foundation's engineering team. It provides helpful information to first time and veteran contributors alike.
Jisort! is a mofo-standard compliant repository, we follow these standards where ever applicable.
You can review the guidebook [here](https://github.com/MozillaFoundation/mofo-standards).
## Building Jisort App
There are currently four build types for Jisort! See the table below for a description of each one.
| Build Type | Description |
| ---------- | ----------- |
| debug | Recommended build type for testing code changes |
| latest | Strips semantic versioning information, used for build deployment |
| qualityassurance | Considered a "pre-release" build candidate for release |
| release | Approved release build, signed with non-debug Mozilla signature |
To assemble a specific build type, append it to the end of the assemble build type like this:
```./gradlew assembleDebug```
If you don't specify a build type (i.e. ```./gradle assemble```) Gradle will assemble all build types.
You can also assemble and install the APK directly on your phone if it's connected over the adb (Android Device Bridge) by using the Gradle ```install``` task and appending the build type you'd like to install to the end like this:
```./gradlew installDebug```

73
docs/CUSTOM.md Normal file
Просмотреть файл

@ -0,0 +1,73 @@
# Customizing Content
Jisort! is an informational app, it runs on data and it's designed to teach people skills. The content you see within Jisort! is completely customizable, making it a great multi-purpose tool for any situation where you want to create an app that teaches people something. You can add your own topics, tutorials, and quizzes without any programming experience.
By default Jisort! comes packaged with it's own built-in content, which you can view [here](https://raw.githubusercontent.com/mozilla/Jisort/master/app/src/main/res/raw/bootstrap_data.json).
## Getting Started
Before we start making our own content, we need to understand how this works. All content goes into a special file format called JSON (JavaScript Object Notation) under the file name ```bootstrap_data.json```. Within our content file, we define objects. An object in this case can be a topic, tutorial or quiz.
Each object has attributes and each of these attributes can be modified. When Jisort! first runs, it parses the content file and saves it to database on first execution. We can change the content by changing object attributes.
## Data Format
Below is the documentation about the format of each type of object supported by Jisort!
### Tutorials
```JSON
{
"tutorials": [
<tutorial>,
<tutorial>,
<tutorial>,
...
]
}
```
Where each `<tutorial>` has this format:
```JSON
{
"id": "1",
"tag": "wifi",
"header": "Wi-Fi ni Noma!",
"photoUrl": "url",
"steps": [{
"id": "1",
"title": "What is Wi-Fi?",
"gifUrl": "wifi1",
"description": "Wi-Fi is a technology that helps your phone connect to the internet, similar to airtime or mobile data. However, <b>Wi-Fi doesn't use your airtime or mobile data.</b> Instead, in coffee shops or public spaces, Wi-Fi is often free."
}, {
"id": "2",
"title": "Where do I get it? Who owns it?",
"gifUrl": "wifi2",
"description": "Wi-Fi networks are created by \"hotspots\" that connect to the internet. Anyone can buy one and set it up at home, at work, or in a public space. If you can detect a Wi-Fi network on your phone, you might be able to connect to it. To learn more about connecting, check out Connecting to Wi-Fi."
}, {
"id": "3",
"title": "Saving Money",
"gifUrl": "wifi3",
"description": "Wi-Fi is great for saving money because it lets you connect to the internet without using mobile data or airtime on your phone. Remember, though, sometimes you have to pay a small fee to use Wi-Fi at a business or cafe, or buy some goods."
}, {
"id": "4",
"title": "Speed and Stability",
"gifUrl": "wifi4",
"description": "Wi-Fi networks are generally more stable and faster than mobile data networks. Wi-Fi was designed to support multiple smartphones at once and lots of internet browsing. Downloading files or streaming videos is best over Wi-Fi.\n<b>Be aware:</b> it is not <b>always</b> the case that Wi-Fi is faster and more stable than mobile data. Depending on infrastructure, popularity, and other environmental factors, Wi-Fi may not be as responsive or reliable."
}]
}
```
## Adding Content
It's super simple and easy to add your own content, however here are a few things to keep in mind while doing so.
- Always increment the id when adding more tutorials, or steps to a tutorial.
- Having two tutorials or steps with the same id can lead to bugs, crashes or unexpected behavior.
- If you're adding custom images, make sure you place them in the ```drawable-nodpi``` before referencing them in your content.
- You can reference images by using the name of the image, minus it's extension (i.e png, gif)
- Verify that your content is being formatted correctly, and use short tutorial headers.
You can also use HTML and Emojis to help you build your own custom content. Jisort! supports a large variety of HTML tags, and over 140+ emojis.
Happy Customizing! :rocket:

Двоичные данные
docs/img/android-run-btn.png Normal file

Двоичный файл не отображается.

После

Ширина:  |  Высота:  |  Размер: 487 KiB

Двоичные данные
docs/img/android-studio-menu.png Normal file

Двоичный файл не отображается.

После

Ширина:  |  Высота:  |  Размер: 361 KiB