[*] update and add READMEs to each package

Summary: Adding READMEs for easy and helpful browsing on GitHub. Also add missing script and `--interpreter` flag Test Plan: Run new launch commands Reviewers: mark, spang, juan, halla Reviewed By: spang, juan, halla Differential Revision: https://phab.nylas.com/D3971
ohsevin · Feb 18, 2017 · 27c08d8 · 27c08d8
1 parent bb0eb2a
commit 27c08d8
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -35,4 +35,4 @@ benefit of letting us use subdomains.
 
 1. `npm install` (Only on fresh install and new packages)
 1. `npm run start-client`: Starts Electron app client
-1. `npm run start-api`: Starts cloud API locally
+1. `npm run start-cloud`: Starts cloud API locally
diff --git a/package.json b/package.json
@@ -50,6 +50,7 @@
     "build-client": "",
 
     "start-cloud": "pm2 stop all; pm2 delete all; pm2 start packages/cloud-core/pm2-dev.yml --no-daemon",
+    "start-cloud-debug": "pm2 stop all; pm2 delete all; pm2 start packages/cloud-core/pm2-debug-cloud-api.yml --no-daemon",
     "test-cloud": "",
     "stop": "npm run stop-cloud",
     "stop-cloud": "pm2 stop all; pm2 delete all;",

diff --git a/packages/README.md b/packages/README.md
@@ -0,0 +1,10 @@
+# Monorepo Packages
+
+Each folder here is designed to act as its own repository. For development
+convenience, they are all included here in one monorepo. This allows us to grep
+across multiple codebases, not use submodules, and keep a unified commit
+history.
+
+We use [Lerna](https://github.com/lerna/lerna) to manage the monorepo and tie
+them all together with the main `nylas-mail-all/scripts/postinstall.js` script,
+which in turn, calls `lerna bootstrap`
diff --git a/packages/client-sync/README.md b/packages/client-sync/README.md
@@ -0,0 +1,27 @@
+# Client Sync
+
+This is the mail sync engine that runs within the Nylas Mail client
+
+It is symlinked in as an `internal_package` of Nylas Mail via the `postinstall`
+script of the root repo.
+
+## Important Usage Notes:
+
+Since this is symlinked in as an `internal_package` of Nylas Mail, there are a
+handulf of considerations when developing in client-sync. Some common gotchas:
+
+- You MAY use `NylasEnv`, `NylasExports` and other injected libraries in the
+  Nylas Mail client environment.
+- You MAY use any 3rd party library declared in `client-app/package.json`.
+  Since this gets added as a plugin of the Nylas Mail client, you'll have
+  access to all libraries. This works because the `client-app/node_modules` was
+  added to the global require paths. That lets us access client-app plugins
+  without being a file directory decendent of client-app (client-sync is now a
+  sibling of client-app)
+- You may NOT add "dependencies" to the `client-sync/package.json`. If you need
+  a 3rd party library, add it to the main `client-app/package.json`. All Nylas
+  Mail plugins (those inside of `internal_packages`), may no longer declare
+  their own dependencies.
+- You should be aggressive at moving generic mail methods to `isomorphic-core`.
+  We may eventually want to make large chunks of client-sync work in a cloud
+  environment as well.
diff --git a/packages/isomorphic-core/README.md b/packages/isomorphic-core/README.md
@@ -0,0 +1,28 @@
+# Isomorphic Core
+
+Isomorphic refers to javascript that can be run on both the client and the
+server.
+
+This is shared code for mail and utilities that is designed to run both on
+deployed cloud servers and from within the Nylas Mail client.
+
+Use through a regular import: `import iso-core from 'isomorphic-core'`
+
+It is required as a dependency in the package.json of other modules.
+
+This library isn't on the npm registry, but works as a dependency thanks to
+`lerna bootstrap`
+
+See index.js for what gets explicitly exported by this library.
+
+## Important Usage Notes:
+
+Since this code runs in both the client and the server, you must be careful
+with what libraries you use. Some common gotchas:
+
+- You can't use `NylasEnv` or `NylasExports`. These are injected only in the
+  client.
+- If you require a 3rd party library, it must be added to the "dependencies" of
+  isomorphic-core's `package.json`
+- You may use modern javascript syntax. Both the client and server get compiled
+  with the same .babelrc setting