###External Documents

Our Postmortem report can be found here

The updated SRS -- contained in a single document -- can be found here . The original Software Requirements Specification is located here.

The updated SDS can be found here. The original Software Design Specification is located here.

Our User Testing Feedback Analysis is located here.

A Code Review Document discussing the changes which lead to the birth of the GoogleGPSUtils class can be found here.

The Design Changes and Rationale Document is located in the Design Changes and Rationale Directory in this repository.

Homesafe - Developer Documentation

###Table of Contents

1. New to HomeSafe
2. Getting Started

• Downloading APK
• Cloning the repository
• Building HomeSafe

3. Developing HomeSafe

• Testing
• Automated Builds and Testing
• Releasing a New Version
• Report a bug

###New to HomeSafe? New to the HomeSafe security app? Read the short product description to find out more about it!

###Getting Started The HomeSafe Security app is an open-source safety app for Android devices. In order to use the app or contribute to the project, you will first need to download the repository from the Github webpage:

• Never used Github before? No problem, start here!
• For everyone else here's a handy Github cheatsheet!

###Downloading APK

• Final Release (requires Android 4.4+)

• Release Candidate (requires Android 4.4+)

• Feature Complete Release (requires Android 5.0+)

• Beta Release (requires Android 5.0+)

• Zero Feature Release

• You may also find the built APK under HomeSafe/app.

###Cloning the Repository Open a terminal window (or a Git terminal window for non-Linux users) and enter

git clone https://github.com/HomeSafe/homesafe

this will create a local copy of the HomeSafe repository on your machine so you will now have access to the most recent copy of the source code.

Before you start adding code or making changes, open your copy of the homesafe repository and make sure that you have all the following items:

$ cd homesafe/
$ ls
  HomeSafe  homesafe.jks  README assets  README.md
$ cd HomeSafe/app/src/
$ ls
  androidTest  main
$ cd main
$ ls
  AndroidManifest.xml  java  res
$ cd java/cse403/homesafe
$ ls
  Data  HSTimer.java  Messaging  StartScreen.java  Trip.java

Note that in the homesafe folder there's a file titled README.md which is a copy of the document you're reading right now.

P.S. if there are any problems at all grabbing the HomeSafe material using git then you can also use the following link to download a zipped version of the HomeSafe source code folder.

###Building HomeSafe There are several options for this step that all boil down to the preference of you, the developer. Android apps are all written in Java; in order to compile and run the HomeSafe source code you need both the Android SDK and an IDE. Two staple Android dev IDEs are Eclipse and Android Studio. Both Eclipse and Android Studio are powerful tools to run Android Java code and have features to test code on both Android devices or emulators. It's super neat and easy to get started with either of these if you don't have either installed. If you've never used either tool before, try to spend a half an hour to learn how to use them before continuing on.

Once you are inside your chosen IDE (Android Studio is used for demonstration in this tutorial) open the project folder; the actual java source code is located in the HomeSafe/app/src/main/java/cse403/homesafe folder and all the layout source files you might need are located in the HomeSafe/app/src/main/res. Any user documentation you might need is on the HomeSafe website, please read it if you need a high-level view of the product.


When you first open the project folder in your IDE you should get a file structure similar to the one shown in the above picture.

Once you have added any code you want and are ready to build, locate and press the build button in your IDE (in Android Studio it is under the Build menu). You can then run the code and test it in an Android Device Emulator.

###Testing Your Software and Not Breaking Ours Testing is very important (especially if you plan to add your code to our code). Please test your code thoroughly and make sure it builds and runs correctly before adding it to the repository. DO NOT ADD BROKEN CODE. If you don't know where to start in terms of testing here are a few handy sites to get you started:

• Android testing
• JUnit Testing
• JUnit Testing in Eclipse

####Unit Test To run the whole unit test suite at once, navigate to the project's top-level directory (homesafe/HomeSafe). From here, you can run the command:

$ ./gradlew test

This will build and run all tests in app/src/test/java directory. Once the tests have completed, you may find a detailed report in the file

app/build/outputs/reports/androidTests/connected/index.html.

Report looks like this:  If you'd like to run individual tests, you'll find core class JUnit tests in app/src/main/java/UnitTests/

To run individual tests from Android Studio, you'll need to manually switch back and forth between the two modes: unit testing mode and instrumentation testing mode. If you're running Android Studio 1.1 or below, make sure unit testing is enabled first by going to Preferences > Build Tools > Gradle > Experimental and ticking the Unit Testing box (this step is unnecesssary in newer versions).

To run unit tests, go to View > Tool Windows > Build Variants and pick Unit Tests in the dropdown. ####System Test System tests can be found in:

app/src/androidTest/java/cse403/homesafe/test/   

To run system test, you will need an Android phone, or test environment that has emulator built in.

####Code Coverage We use code coverage library Jacoco for test coverage. It is configured in build.gradle to run all the unit tests and compare with code in src/main/java/ directory.
In project's top-level directory, run:

./gradlew jacocoTestReport

Coverage report can be found in:

/app/build/reports/jacoco/jacocoTestReport/html/index.html

Report looks like this:  (We aim to cover most of the data classes in our project. Android Activities and functionalities (database, SMS, etc.) that depend on Android system are tested in system tests, the coverage is not supported)

###Setting Up Automated Builds and Tests Building and testing can be a pain; if you're interesting in setting up automated daily builds the following sites can help you on your way to setting some up: Jenkins, CruiseControl, Cron.

You may also use Travis CI. We've provided a travis.yml file in the top level directory for continuous integration. This will automatically build and test the application on commit and at a specified schedule.

###Releasing a New Version Before adding anything to the repository please update the version name located in the Androidmanifest.xml and build.grade files by incrementing the decimal portion by 1 (so 1.1 becomes 1.2 and 1.9 becomes 1.10 and so on). This is for good book keeping, and let's us know what is featured in which version. Highlighted below in the photos are the specific items to be changed.



###Where to Find Our Bug List and Add to It File a bug report here. In your report, make sure to include your device model, your operating system release, and a quick description of the bug and how to reproduce it. Please follow these bug reporting guidelines.