docs(readme): creating an initial readme (#226)

* docs(readme): creating an initial readme

* docs(readme): adding back accidental commit removal

* docs(readme): adding a baseline readme

* docs(readme): updating formatting

Author: bassrock

Config/secrets.xcconfig.example

@@ -0,0 +1 @@
+POCKET_API_CONSUMER_KEY=test-consumer-key

Pocket.xcodeproj/project.pbxproj

@@ -142,6 +142,7 @@
 		16E4B16E27A3212900E01746 /* Response+factories.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Response+factories.swift"; sourceTree = "<group>"; };
 		16EE3F4F26CEC80900249AF4 /* PullToRefreshTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PullToRefreshTests.swift; sourceTree = "<group>"; };
 		16FCADBE26CB04AC00906C03 /* ArchiveAnItemTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ArchiveAnItemTests.swift; sourceTree = "<group>"; };
+		655C274E28B67ED20040AEAB /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = "<group>"; };
 		8A289CD52899BD820030E5E0 /* BannerViewTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BannerViewTests.swift; sourceTree = "<group>"; };
 		8A3E3DBB2864DB0500483564 /* EmptyStateTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EmptyStateTests.swift; sourceTree = "<group>"; };
 		8A4ECEF8287775F90007DB67 /* SectionHeaderElement.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SectionHeaderElement.swift; sourceTree = "<group>"; };
@@ -203,6 +204,7 @@
 		166A81A32637406B0015AA1D = {
 			isa = PBXGroup;
 			children = (
+				655C274E28B67ED20040AEAB /* README.md */,
 				166DF27827E9172800C03BF4 /* Pocket (iOS).entitlements */,
 				1624B85A268508180099B6EF /* PocketKit */,
 				16BA7D6226851513009A17C1 /* main.swift */,

README.md

@@ -1 +1,94 @@
-# Pocket iOS
+# Pocket iOS
+
+Welcome to the Next iteration of the Pocket iOS client, currently in development.
+
+# Getting Started
+
+## Setup Pocket Secrets File
+
+To develop Pocket for iOS, you need to first obtain a 1st party Pocket consumer key, which is available to internal Pocket & Mozilla Employees.
+
+Once obtained you can run the following command from the root directory:
+
+```
+cp Config/secrets.xcconfig.example Config/secrets.xcconfig
+```
+
+Then replace values in `Config/secrets.xcconfig` with the values you have received.
+
+## Pocket Graph (API) Schema
+
+Pocket for iOS uses an autogenerated API.swift file that is created by the Apollo CodeGen target.
+
+### Downloading Graph Schema
+
+To download a new version of [`PocketKit/Sources/Sync/schema.graphqls`](./PocketKit/Sources/Sync/schema.graphqls) you can run the following commands:
+
+```bash
+cd PocketKit/Sources/ApolloCodegen/
+swift run ApolloCodegen download-schema
+```
+
+### Generating API.swift
+
+To download a new version of [`PocketKit/Sources/Sync/API.swift`](./PocketKit/Sources/Sync/API.swift) you can run the following commands:
+
+```bash
+cd PocketKit/Sources/ApolloCodegen/
+swift run ApolloCodegen generate
+```
+
+### Future
+
+We plan on implementing the following changes in the future:
+
+- Ensure that the [`PocketKit/Sources/Sync/schema.graphqls`](./PocketKit/Sources/Sync/schema.graphqls) and [`PocketKit/Sources/Sync/API.swift`](./PocketKit/Sources/Sync/API.swift) are generated on demand at build time.
+  - Blocked by needing [Swift Build Tool support in Apollo](https://github.com/apollographql/apollo-ios/pull/2464)
+
+## Build Targets
+
+### Apollo CodeGen
+
+Apollo CodeGen is a build target setup to download and generate the GraphQL schemas provided by the [Pocket Graph](https://github.com/Pocket/client-api).
+
+How to use it can be seen in [Generating API Schema](#Generating API Schema) above.
+
+### Pocket Kit
+
+Pocket Kit is the foundation of all of Pocket. Pocket is purposefully abstracted into a Kit so that we can define multiple targets in the Apple Ecosystem and still use the same code base. Here you can find the view controllers, app delegates and most entrypoints into the Pocket application.
+
+### Sync
+
+Sync is the main API & Core Data layer that Pocket is built on. This library provides the work needed to communicate with the Pocket API and our Offline storage layer, backed by CoreData.
+
+### Textile
+
+Textile provides the standard views and styles that can be re-used across all of the Pocket targets we create in the Apple Ecosystem.
+
+### Analytics
+
+Analytics provides Pocket's implementation of [Snowplow](https://github.com/snowplow/) which we use to provide a feedback loop to the Pocket product team into how our features are used.
+
+### Save To Pocket Kit
+
+Save to Pocket Kit is the code base needed to make the Pocket Share Extension function and is embeded in the SaveToPocket Extension that enables you to Save to Pocket from other applications.
+
+### Shared Pocket Kit
+
+Shared Pocket Kit contains the main bits for session management and keychain storage that is used across all apps in the Pocket App Group.
+
+## Developing in Pocket
+
+### Commit strategy
+
+We prefer to keep out commit history linear (meaning avoiding noisy merge
+commits). To keep your branch up to date, follow these steps:
+
+```bash
+# while on your PR branch
+git checkout develop
+git pull --rebase
+git checkout my-pr-branch
+git rebase develop
+git push origin my-pr-branch --force[-with-lease]
+```