From 610b432ba304cc46445f336198c0cecca29174d8 Mon Sep 17 00:00:00 2001 From: Sebastian McKenzie Date: Tue, 1 Sep 2015 05:05:32 +0100 Subject: [PATCH] add docs --- doc/api/node-path.md | 0 doc/api/scope.md | 0 doc/design/monorepo.md | 40 ++++++++++++++++++++++++++++++++++++++++ doc/design/versioning.md | 5 +++++ doc/index.md | 4 ---- doc/node-props.md | 11 ----------- 6 files changed, 45 insertions(+), 15 deletions(-) create mode 100644 doc/api/node-path.md create mode 100644 doc/api/scope.md create mode 100644 doc/design/monorepo.md create mode 100644 doc/design/versioning.md delete mode 100644 doc/index.md delete mode 100644 doc/node-props.md diff --git a/doc/api/node-path.md b/doc/api/node-path.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/api/scope.md b/doc/api/scope.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/design/monorepo.md b/doc/design/monorepo.md new file mode 100644 index 0000000000..e5bc09bdb4 --- /dev/null +++ b/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) diff --git a/doc/design/versioning.md b/doc/design/versioning.md new file mode 100644 index 0000000000..030fd87110 --- /dev/null +++ b/doc/design/versioning.md @@ -0,0 +1,5 @@ +# How does Babel versioning work? + +## Does Babel follow semver? + +Yes. diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index 5a87389d00..0000000000 --- a/doc/index.md +++ /dev/null @@ -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). diff --git a/doc/node-props.md b/doc/node-props.md deleted file mode 100644 index 3fec49b615..0000000000 --- a/doc/node-props.md +++ /dev/null @@ -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.