diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 08bef1144c..1e288b5ce7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,9 @@ We welcome participation in an open project. We want to make it as easy as possible for people to work together, so please follow these guidelines to prepare and submit a pull request. -## How to prepare +- Filtering by [good first issues](https://github.com/tripleblindmarket/covid-safe-paths/labels/good%20first%20issue) is the recommended way to begin contributing to the project + +## Create A New Issue - You need a Github account. You can [create one](https://github.com/signup/free) for free. diff --git a/README.md b/README.md index 9695c39f35..924892a307 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,160 @@ -# COVID Safe Paths ![Android and iOS build on MacOS](https://github.com/tripleblindmarket/covid-safe-paths/workflows/Android%20and%20iOS%20build%20on%20MacOS/badge.svg) - -**Applying the technology and philosophy of Private Kit to COVID** +
+

COVID Safe Paths

+ + + safe paths logo + + +

+ Applying the technology and philosophy of Private Kit to COVID-19 +

+ + **https://covidsafepaths.org | https://safepaths.mit.edu** +
+ +
Help us stop COVID-19. -We’re building the next generation of secure location logging to preserve privacy and #flattenthecurve +We’re building the next generation of secure location logging to preserve privacy and _#flattenthecurve_ Location logs provide time-stamped records of where users have been, allowing them to share information with health officials accurately and quickly. This helps support contact tracing efforts to slow the spread of the virus. -What’s truly special about Safe Paths, though, is its privacy protection. Data never leaves a user's device without their password entry and explicit consent. The location log generated by Safe Paths cannot be accessed from outside the user’s device, meaning data transfer occurs only if the user chooses to share it with a researcher or health official. +What’s truly special about Safe Paths, though, is its privacy protection. ----- +Data never leaves a user's device without their password entry and explicit consent. The location log generated by Safe Paths cannot be accessed from outside the user’s device, meaning data transfer occurs only if the user chooses to share it with a researcher or health official. -Safe Paths is a ‘privacy-first’ app that allows you to log your GPS trails on your own phone. The information is stored locally and never shared with anyone (not even with us or MIT) until you explicitly decide to manually export the data. The location log generated by Safe Paths cannot be accessed from outside the user’s device. Location information can be imported and exported by the user and used in other projects and applications. +## Overview + +Safe Paths is a ‘privacy-first’ app that allows you to log your GPS trails on your own phone. The information is stored locally and never shared with anyone (not even with us or MIT) until you explicitly decide to manually export the data. + +The location log generated by Safe Paths cannot be accessed from outside the user’s device. However, the user can import and export their location information and use it in other projects and applications. Safe Paths logs your device’s location once every five minutes and stores 28 days of data in under 100KB of space. -**Home page:** https://covidsafepaths.org and https://safepaths.mit.edu +### Private Kit WhitePaper + +[Apps Gone Rogue: Maintaining Personal Privacy in an Epidemic](https://drive.google.com/file/d/1nwOR4drE3YdkCkyy_HBd6giQPPhLEkRc/view?usp=sharing) + +### Downloads for COVID Safe Paths + +_coming soon!_ -**Private Kit WhitePaper:** [Apps Gone Rogue: Maintaining Personal Privacy in an Epidemic](https://drive.google.com/file/d/1nwOR4drE3YdkCkyy_HBd6giQPPhLEkRc/view?usp=sharing) +### Downloads for Private Kit (technology beta) -**Downloads for COVID Safe Paths:** _coming soon!_ +[Google Play](https://play.google.com/store/apps/details?id=edu.mit.privatekit) | [Apple Store](https://apps.apple.com/us/app/private-kit-prototype/id1501903733) -**Downloads for Private Kit (technology beta):** [Google Play](https://play.google.com/store/apps/details?id=edu.mit.privatekit) | [Apple Store](https://apps.apple.com/us/app/private-kit-prototype/id1501903733) +
# Development Overview -This is a React Native app version 61.5 +![Android and iOS build on MacOS](https://github.com/tripleblindmarket/covid-safe-paths/workflows/Android%20and%20iOS%20build%20on%20MacOS/badge.svg) + +_Safe Paths_ is a built on [React Native](https://reactnative.dev/docs/getting-started) v0.61.5 + +## Contributing + +Read the [contribution guidelines](CONTRIBUTING.md). ## Architecture -Please refer to `docs/Private Kit Diagram.png` for a basic overview on the sequencing of generalized events and services that are used by Safe Paths. +View the [architecture diagram](docs/Private_Kit_Diagram.png) for a basic overview on the sequencing of generalized events and services that are used by Safe Paths. ## Developer Setup -Run the ```dev_setup.sh``` (Linux/MacOS) or ```dev_setup.bat``` (Windows) for needed tools. It is assumed that Android Studio and/or xcode (on macOS) is set up and configured correctly to run applications in the simulator. For Android Studio, the dev_setup script can help you, but you still may need to configure at least one android virtual device (avd) from within Android Studio first before you can run the app. +First, run the appropriate setup script for your system. This will install relevant packages, walk through Android Studio configuration, etc. -## Running +**Note:** You will still need to [configure an Android Virtual Device (AVD)](https://developer.android.com/studio/run/managing-avds#createavd) after running the script. -```yarn``` must be installed for this project, as it does a better job installing dependendies across platforms. The dev_setup script above should have done that for you. +#### Linux/MacOS -### Install modules to the correct locations +``` +dev_setup.sh +``` + +#### Windows -1. ```yarn install``` (always do this after a new clone or checkout) -2. ```yarn install:pod``` (additional step for macOS if you want to do an iOS build) +``` +dev_setup.bat +``` -### Run the app in a simulator +## Running + +**Note:** In some cases, these procedures can lead to the error `Failed to load bundle - Could not connect to development server`. In these cases, kill all other react-native processes and try it again. + +#### Android (Windows, Linux, macOS) -To run in the Android simulator (Windows, Linux, macOS): ``` npx react-native run-android ``` -or (on macOS only) + +Device storage can be cleared by long-pressing on the app icon in the simulator, clicking "App info", then "Storage", and lastly, "Clear Storage". + +#### iOS (macOS only) + ``` +yarn install:pod ## only needs to be ran once npx react-native run-ios ``` -NOTE: In some cases, these procedures can lead to the error `Failed to load bundle - Could not connect to development server`. In these cases, kill all other react-native processes and try it again. +Device storage can be cleared by clicking "Hardware" on the system toolbar, and then "Erase all content and settings". -## Contributing +### Release Builds -Read the [contribution guidelines](CONTRIBUTING.md). +Generating a release build is an optional step in the development process. + +- [Android instructions](https://reactnative.dev/docs/signed-apk-android) + +### Debugging + +[react-native-debugger](https://github.com/jhen0409/react-native-debugger) is recommended. This tool will provide visibility of the JSX hierarchy, breakpoint usage, monitoring of network calls, and other common debugging tasks. + +## Testing + +Tests are ran automatically through Github actions - PRs are not able to be merged if there are tests that are failing. + +### Unit Test + +To run the unit tests: + +``` +yarn test --watch +``` + +[Snapshot testing](https://jestjs.io/docs/en/snapshot-testing) is used as a quick way to verify that the UI has not changed. To update the snapshots: + +``` +yarn update-snapshots +``` + +### e2e Test +**Note:** Right now, there is only e2e test support for iOS. + +e2e tests are written using [_detox_](https://github.com/wix/Detox). Screenshots of each test run are saved to `e2e/artifacts` for review. + +To run the e2e tests: + +``` +yarn detox-setup ## only needs to be run once +yarn build:e2e:ios ## needs to be run after any code change +yarn test:e2e:iphone{11, -se, 8} +``` +### Manual Device Testing +Mobile devices come in many different shapes and sizes - it is important to test your code on a variety of simulators to ensure it looks correct on all device types. +Before pushing up code, it is recommended to manually test your code on the following devices: +- Nexus 4 (smaller screen) +- iPhone 8 (smaller screen) +- Pixel 3 XL (larger screen) +- iPhone 11 (screen w/ notch) diff --git a/assets/Safe_Paths_Logo.png b/assets/Safe_Paths_Logo.png new file mode 100644 index 0000000000..4fab91bd7b Binary files /dev/null and b/assets/Safe_Paths_Logo.png differ diff --git a/docs/Private Kit Diagram.png b/docs/Private_Kit_Diagram.png similarity index 100% rename from docs/Private Kit Diagram.png rename to docs/Private_Kit_Diagram.png diff --git a/reset_react.sh b/reset_react.sh deleted file mode 100755 index 71aa5bc657..0000000000 --- a/reset_react.sh +++ /dev/null @@ -1,11 +0,0 @@ -rm -rf node_modules -rm package-lock.json -rm yarn.lock -rm -rf ios/Pods -rm ios/Podfile.lock - -yarn install -cd ios -pod install -cd .. -