chore: update repository documentation (#785)

Author: jamesonwilliams

CONTRIBUTING.md

@@ -40,15 +40,15 @@ environment variables are set. A convenient way of doing this is to add them
 into `~/.bashrc`. On a Mac, the SDK and Java installation used by the SDK may
 be found:
 
-```
+```shell
 export ANDROID_HOME=~/Library/Android/sdk
 export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jre/jdk/Contents/Home
 ```
 Note: JDK 11, 12, 13, etc. have known issues and are not supported.
 
 Now, clone the Amplify Android project from GitHub.
 
-```
+```shell
 git clone [email protected]:aws-amplify/amplify-android.git
 ```
 Load this project into Android Studio by selecting File > Open, and choosing
@@ -59,7 +59,7 @@ In Android Studio, build the project by clicking the Hammer icon, "Make
 Project ⌘F9". If working on the command line, you can do the same thing
 via:
 
-```
+```shell
 ./gradlew build
 ```
 
@@ -74,7 +74,7 @@ The local Maven repository is usually found in your home directory at
 To publish the outputs of the build, execute the following command from
 the root of the `amplify-android` project:
 
-```
+```shell
 ./gradlew publishToMavenLocal
 ```
 
@@ -88,7 +88,7 @@ buildscript {
         mavenLocal() // this should ideally appear before other repositories
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.6.3'
+        classpath 'com.android.tools.build:gradle:4.0.1'
     }
 }
 
@@ -128,14 +128,29 @@ AndroidX test core, runner, and a jUnit extension. See Android's notes on
 Be aware of the Getting Started and Pull Request guides. This portion deals
 actually with changing some code.
 
-First, identify the module you'll modify:
+First, identify the module you'll modify. The various Gradle modules are
+described below:
 
  - `core` - The Framework itself, including category behavior definitions
- - `aws-datastore` - An AppSync implementation of the datastore contract
- - `aws-api` - A utility to talk to GraphQL and REST endpoints
- - `aws-storage-s3` - Wrapper around S3
- - `aws-analytics-pinpoint` - Wrapper around Pinpoint
- - `testutilts` - Utility code, helpful when writing unit and instrumentation
+ - `aws-auth-cognito` - A plugin implementation of the Auth category that
+    speaks to Amazon Cognito through the legacy `AWSMobileClient` utility
+ - `aws-datastore` - An AppSync-based plugin for the DataStore category
+ - `aws-api` - Plugin for API category with special abilities to talk to
+    AppSync and API Gateway endpoints
+ - `aws-api-appsync` - AppSync implementation details that are shared
+    accross multiple plugins implementations (`aws-api`, `aws-datastore`)
+ - `aws-storage-s3` - A plugin for the Storage category, leveraging S3, Cognito
+ - `aws-predictions` - A plugin for Predictions category, leveraging
+    numerous Amazon machine learnings services.
+ - `aws-predictions-tensorflow` - A plugin for the Predictions category
+    which does machine learning on the device, using TensorFlow Lite
+ - `aws-analytics-pinpoint` - A plugin for the Analytics category,
+    leveraging Amazon Pinpoint
+ - `rxbindings` - A front-end for Amplify that expresses operations as
+    Rx primitives
+ - `amplify-tools` - A Gradle plugin that can be used to run Amplify CLI
+    commands from within the Android Studio IDE.
+ - `testutils` - Utility code, helpful when writing unit and instrumentation
 	tests. A lot of it deals with making async code synchronous, for more
     legible tests.
  - `testmodels` - Models that are used in test code. These were generated by
@@ -155,14 +170,14 @@ conventions and expectations for source files in the Android codebase.
 For example, let's say you want to add a `Merger` component to the AppSync
 Local implementation. Create a file in that module, and a unit test for it:
 
-```
+```console
 aws-datastore/src/main/com/amplifyframework/datastore/syncengine/Merger.java
 aws-datastore/src/test/com/amplifyframework/datastore/syncengine/MergerTest.java
 ```
 
 The code below might be a reasonable template for these new files.
 
-```
+```java
 /*
  * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
@@ -203,7 +218,7 @@ final class Merger {
 ```
 
 
-```
+```java
 /*
  * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
@@ -285,7 +300,7 @@ Some suggestions include:
 This will perform a clean build, run Checkstyle, Android Lint, and all unit
 tests. This must complete successfully before proposing a PR.
 
-```
+```shell
 ./gradlew clean build
 ```
 
@@ -302,21 +317,21 @@ configurations suitable for running the integration tests.
 If you are part of the private access list, the command below will copy
 those configurations to your local workspace:
 
-```
+```shell
 cd amplify-android
 .circleci/copy-configs
 ```
 
 To run a __specific__ test:
 
-```
+```shell
 test='com.amplifyframework.api.aws.RestApiInstrumentationTest#getRequestWithIAM'
 ./gradlew :cAT -Pandroid.testInstrumentationRunnerArguments.class="$test"
 ```
 
 To run __all__ tests:
 
-```
+```shell
 ./gradlew cAT
 ```
 
@@ -343,7 +358,7 @@ This is mostly the same as [GitHub's guide on creating a pull request](https://h
 
 First, create a _fork_ of `amplify-android`. Clone it, and make changes to this _fork_.
 
-```
+```shell
 git clone [email protected]:your_username/amplify-android.git 
 ```
 
@@ -357,7 +372,7 @@ describing what you've done, include links to useful resources. These might
 include design documents, StackOverflow implementation notes, GitHub issues,
 etc. All links must be publicly accessible.
 
-```
+```console
 [aws-datatore] Add a 3-way merging component for network ingress
 
 The Merger checks the state of the Mutation Outbox before applying
@@ -370,26 +385,22 @@ See also: https://stackoverflow.com/a/58662077/695787
 
 Now, save your work to a new branch:
 
-```
+```shell
 git checkout -B add_merger_to_datastore
 ```
 
 To publish it:
 
-```
+```shell
 git push -u origin add_merger_to_datastore
 ```
 
 This last step will give you a URL to view a GitHub page in your browser.
 Copy-paste this, and complete the workflow in the UI. It will invite you to
 "create a PR" from your newly published branch.
 
-Your should add the
-**[Amplify-Native](https:~~/~~/github.com/orgs/aws-amplify/teams/amplify-native)**
-team as a reviewer of your PR.
-
-Your PR must be reviewed by at least one member of this team, in order to be
-considered for inclusion.
+Your PR must be reviewed by at least one repository maintainer, in order
+to be considered for inclusion.
 
 your PR must also pass the CircleCI workflow and LGTM validations. CircleCI
 will run all build tasks (Checkstyle, Lint, unit tests).
@@ -403,26 +414,26 @@ the PR.
 ### Environment Debugging
 
 Are you using the right versions of Gradle, Ant, Groovy, Kotlin, Java, Mac OS X?
-```
+```console
 ./gradlew -version
 
 ------------------------------------------------------------
-Gradle 6.3
+Gradle 6.6
 ------------------------------------------------------------
 
-Build time:   2020-03-24 19:52:07 UTC
-Revision:     bacd40b727b0130eeac8855ae3f9fd9a0b207c60
+Build time:   2020-08-10 22:06:19 UTC
+Revision:     d119144684a0c301aea027b79857815659e431b9
 
-Kotlin:       1.3.70
-Groovy:       2.5.10
-Ant:          Apache Ant(TM) version 1.10.7 compiled on September 1 2019
-JVM:          1.8.0_212-release (JetBrains s.r.o 25.212-b4-5784211)
-OS:           Mac OS X 10.14.6 x86_64
+Kotlin:       1.3.72
+Groovy:       2.5.12
+Ant:          Apache Ant(TM) version 1.10.8 compiled on May 10 2020
+JVM:          1.8.0_242-release (JetBrains s.r.o 25.242-b3-6222593)
+OS:           Mac OS X 10.15.6 x86_64
 ```
 
 Do you have the Android SDK setup, and do you have a pointer to the Java environment?
 
-```
+```console
 echo -e $ANDROID_HOME\\n$JAVA_HOME 
 /Users/jhwill/Library/Android/sdk
 /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home
@@ -433,14 +444,14 @@ echo -e $ANDROID_HOME\\n$JAVA_HOME
 If the build fails, and you can't figure out why from a Google search /
 StackOverflow session, try passing options to Gradle:
 
-```
+```shell
 ./gradlew --stacktrace
 ```
 
 The next flag will spit out lots of info. It's only useful if you pipe the
 output to a file, and grep through it.
 
-```
+```shell
 ./gradlew --debug 2>&1 > debugging-the-build.log
 ```
 
@@ -450,7 +461,7 @@ If a single test is failing, run only that test, to isolate it. You may also
 want to see the output on the device that occurs, while the tests are
 executing.
 
-```
+```shell
 # If you run this same code in a script/block, this will clear the log
 # file each time.
 rm -f device-logs-during-test.log
@@ -476,24 +487,17 @@ iOS, and numerous JavaScript-based web platforms. The Amplify CLI
 provides an entry point to configure backend resources for all of these
 platforms.
 
-1. [AWS Amplify CLI](https://github.com/aws-amplify/amplify-cli)
+1. [AWS Amplify for Flutter](https://github.com/aws-amplify/amplify-flutter)
 2. [AWS Amplify for iOS](https://github.com/aws-amplify/amplify-ios)
 3. [AWS Amplify for JavaScript](https://github.com/aws-amplify/amplify-js)
+4. [AWS Amplify CLI](https://github.com/aws-amplify/amplify-cli)
 
-AWS Amplify plugins are built on top of the AWS SDKs. AWS SDKs are a
+AWS Amplify plugins are built on top of "low-level" AWS SDKs. AWS SDKs are a
 toolkit for interacting with AWS backend resources.
 
 1. [AWS SDK for Android](https://github.com/aws-amplify/aws-sdk-android)
 2. [AWS SDK for iOS](https://github.com/aws-amplify/aws-sdk-ios)
-3. [AWS SDK for JavaScript](https://github.com/aws/aws-sdk-js)
-
-Not officially part of the AWS SDKs, [AppSync](https://aws.amazon.com/appsync/) is an opinionated,
-mobile-oriented GraphQL management service. It is used by Amplify's
-DataStore and API plugins.
-
-1. [Android AppSync Client](https://github.com/awslabs/aws-mobile-appsync-sdk-android)
-2. [iOS AppSync Client](https://github.com/awslabs/aws-mobile-appsync-sdk-ios)
-3. [JavaScript AppSync Client](https://github.com/awslabs/aws-mobile-appsync-sdk-js)
+3. [AWS SDK for JavaScript](https://github.com/aws/aws-sdk-js-v3)
 
 ## Finding Contributions to Make
 Looking at [the existing issues](https://github.com/aws-amplify/amplify-android/issues) is a
@@ -519,3 +523,4 @@ contribution.
 We may ask you to sign a
 [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for
 larger changes.
+

README.md

@@ -8,18 +8,18 @@
  </a>
 
 
-AWS Amplify provides a high-level interface to perform different categories of
-cloud operations. Each category is fulfilled by a _plugin_. You specify which
-plugins to use during setup.
+AWS Amplify provides a high-level interface to perform different
+**categories** of cloud operations. Each category is fulfilled by a
+**plugin**. You specify which plugins to use during setup.
 
 The default plugins that we provide are designed to facilitate interaction with
-Amazon Web Services (AWS). But, the Amplify framework is designed to be
+Amazon Web Services (AWS). But, the Amplify Framework is designed to be
 extensible to any other backend or service.
 
 To familiarize yourself with Amplify, checkout our [Getting Started
 Guide](https://docs.amplify.aws/start/q/integration/android).
 
-## Features / APIs
+## Categories
 
 - **[Authentication](https://docs.amplify.aws/lib/auth/getting-started/q/platform/android)**
   APIs and building blocks for developers who want to create user authentication
@@ -63,31 +63,46 @@ dependencies section:
 
 ```groovy
 dependencies {
-    implementation 'com.amplifyframework:core:1.1.2'
-
     // Only specify modules that provide functionality your app will use
-    implementation 'com.amplifyframework:aws-analytics-pinpoint:1.1.2'
-    implementation 'com.amplifyframework:aws-api:1.1.2'
-    implementation 'com.amplifyframework:aws-auth-cognito:1.1.2'
-    implementation 'com.amplifyframework:aws-datastore:1.1.2'
-    implementation 'com.amplifyframework:aws-predictions:1.1.2'
-    implementation 'com.amplifyframework:aws-storage-s3:1.1.2'
+    implementation 'com.amplifyframework:aws-analytics-pinpoint:1.3.0'
+    implementation 'com.amplifyframework:aws-api:1.3.0'
+    implementation 'com.amplifyframework:aws-auth-cognito:1.3.0'
+    implementation 'com.amplifyframework:aws-datastore:1.3.0'
+    implementation 'com.amplifyframework:aws-predictions:1.3.0'
+    implementation 'com.amplifyframework:aws-storage-s3:1.3.0'
 }
 ```
 
-### Java 8 Compatibility
+### Java 8 Requirement
 
-Amplify Android uses Java 8 features. Please add a `compileOptions`
+Amplify Android _requires_ Java 8 features. Please add a `compileOptions`
 block inside your app's `build.gradle`, as below:
 
 ```gradle
 android {
     compileOptions {
+        coreLibraryDesugaringEnabled true
         sourceCompatibility JavaVersion.VERSION_1_8
         targetCompatibility JavaVersion.VERSION_1_8
     }
 }
 ```
+In the same file, add core library desugaring in your `dependencies`
+block:
+```gradle
+dependencies {
+    // Add this line
+    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.0.10'
+}
+```
+
+### Rx Support
+
+By default, Amplify's interfaces render results through async callbacks.
+However, we also offer an Rx-compatible front-end to Amplify.
+
+See [Using RxJava with Amplify](https://docs.amplify.aws/lib/project-setup/rxjava/q/platform/android)
+for more information.
 
 ### Authentication
 
@@ -113,3 +128,4 @@ and we'll get back to you.
 ## Contribute to the Project
 
 Please see the [Contributing Guidelines](./CONTRIBUTING.md).
+