add docs

doc/design/monorepo.md

@@ -0,0 +1,40 @@
+# Why is Babel a monorepo?
+
+Juggling a multimodule project over multiple repos is like X.
+
+Babel follows a monorepo approach, all officially maintained modules are in the same repo.
+This is quite taboo but let's look at the pros and cons:
+
+**Pros:**
+
+ * Single lint, build, test and release process.
+ * Easy to coordinate changes across modules.
+ * Single place to report issues.
+ * Easier to setup a development environment.
+ * Tests across modules are ran together which finds bugs that touch multiple modules easier.
+
+**Cons:**
+
+ * Codebase looks more intimidating.
+ * Repo is bigger in size.
+ * ???
+
+## This is dumb! Nobody in open source does this!
+
+[React](https://github.com/facebook/react/tree/master/packages),
+[Ember](https://github.com/emberjs/ember.js/tree/master/packages) among others do this.
+
+## Previous discussion
+
+- [Dan Luu](http://danluu.com/monorepo/)
+- [Gregory](http://gregoryszorc.com/blog/2014/09/09/on-monolithic-repositories/)
+- [Szorc](http://gregoryszorc.com/blog/2015/02/17/lost-productivity-due-to-non-unified-repositories/)
+- [Face](https://developers.facebooklive.com/videos/561/big-code-developer-infrastructure-at-facebook-s-scale)[book](https://code.facebook.com/posts/218678814984400/scaling-mercurial-at-facebook/)
+- [Benjamin Pollack](http://bitquabit.com/post/unorthodocs-abandon-your-dvcs-and-return-to-sanity/)
+- [Benjamin Eberlei](https://qafoo.com/resources/presentations/froscon_2015/monorepos.html)
+- [Simon Stewart](http://blog.rocketpoweredjetpants.com/2015/04/monorepo-one-source-code-repository-to.html)
+- [Digital Ocean](https://www.digitalocean.com/company/blog/taming-your-go-dependencies/)
+- [Google](http://www.infoq.com/presentations/Development-at-Google)
+- [Twitter](http://git-merge.com/videos/scaling-git-at-twitter-wilhelm-bierbaum.html)
+- [thedufer](http://www.reddit.com/r/programming/comments/1unehr/scaling_mercurial_at_facebook/cek9nkq)
+- [Paul Hammant](http://paulhammant.com/categories.html#trunk_based_development)

doc/design/versioning.md

@@ -0,0 +1,5 @@
+# How does Babel versioning work?
+
+## Does Babel follow semver?
+
+Yes.

doc/index.md

@@ -1,4 +0,0 @@
-This is a collection of documentation about babel internals, for use in development of babel.
-
-# [Properties of nodes](/doc/node-props.md)
-These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec (ESTree at the time of this writing).

doc/node-props.md

@@ -1,11 +0,0 @@
-# Properties of nodes
-These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec ([ESTree](https://github.com/estree/estree) at the time of this writing).
-
-## `_blockHoist`
-`node._blockHoist != null` triggers the [block-hoist transformer](/src/babel/transformation/transformers/internal/block-hoist.js). Value should be `true` or an integer in the range `0..3`. `true` is equivalent to `2`. The value indicates whether the node should be hoisted and to what degree. See the source code for more detailed information.
-
-## `_paths`
-Stores a representation of a node's position in the tree and relationship to other nodes.
-
-## `shadow`
-A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and the `this` context from the parent scope. It is invoked for arrow functions, for example.