Add contributing guide, project vision, and code of conduct (#293)

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at alangpierce@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+

CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Sucrase
+
+## Intro
+
+Thanks for taking a look at the project and thinking about contributing!
+
+There are two main ways to communicate about Sucrase development:
+* Join the [Gitter room](https://gitter.im/sucrasejs/Lobby) and feel free to ask
+  questions or discuss anything.
+* File an issue or PR in this repository. Issues don't need to be bug reports;
+  usage questions or suggests are fine.
+
+All contributions and interactions are expected to follow the
+[Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## What kinds of contributions make sense?
+
+There are lots of ways to contribute to Sucrase! The easiest way to get started
+is to just starting using Sucrase for a project and see what issues you run
+into. Did you run into any bugs? Were the details confusing? Is there a way to
+make it easier to use? All of those would be great issues to file in this
+repository!
+
+In addition to filing issues, there are lots of ways to contribute:
+
+* Fix bugs. Be sure to also include a regression test for any bug fix!
+* Add more tests or test infrastructure. Right now, Sucrase runs on a few open
+  source projects as part of its test suite, but it would always be great to add
+  more.
+* Add better performance tests.
+* Add better documentation, like a Getting Started guide.
+* Write more integrations for Sucrase, like a Browserify plugin.
+
+Contributing features, refactors, and performance improvements to the "core" of
+Sucrase (the parser and the transformers) may need some more thought and care.
+See the [Project Vision](./docs/PROJECT_VISION.md) for some thoughts on what
+types of improvements make sense for the project, and make sure to start a
+discussion before getting too deep in the code. Some problems may be best solved
+outside of the core Sucrase code, or may be better as a fork of Sucrase.
+
+See [this issue](https://github.com/alangpierce/sucrase/issues/161) for some
+more concrete suggestions.
+
+## Getting started
+
+Sucrase uses `yarn` for everything.
+
+```
+git clone git@github.com:alangpierce/sucrase.git
+cd sucrase
+yarn  # Install dependencies.
+yarn test  # Run tests.
+yarn build  # Build Sucrase.
+yarn fast-build  # Quickly build Sucrase for development.
+yarn release 1.2.3  # Run the release script, releasing version 1.2.3.
+```
+
+I'd also recommend getting your editor set up nicely to handle TypeScript,
+Prettier, and Mocha.
+
+Contributions should follow the normal GitHub pull request process: fork the
+repo, make a new branch with your change, push the branch, and create a pull
+request with a meaningful title and description, including any interesting
+details of the change and references to any issues closed by the change.
+
+## Code structure
+
+The code is organized as a monorepo (with one primary `sucrase` package and
+several smaller packages/projects). Here are the most important directories:
+* The `src` directory is where the main code lives. Much of the code is in the
+  `parser` subdirectory, which is a heavily modified fork of Babel's parser. The
+  rest of the code handles transforming the code given the result of the parser.
+* The `test` directory has all tests, generally broken down by which transform
+  is most relevant. Nearly all tests simply give code as input and assert the
+  output code. Running a test in debug mode and stepping through different parts
+  of the code is a great way to learn how Sucrase works!
+* The `website` directory contains the full code for the
+  [sucrase.io website](https://sucrase.io).
+* The `integrations` directory has several small packages integrating Sucrase
+  with Webpack, Jest, etc.
+* The `example-runner` directory has code to clone various open source projects,
+  run Sucrase on them, then run the tests to make sure that the Sucrase output
+  was correct. You can run all example projects with `yarn run-examples`.
+* The `generator` directory contains some some utilities for generating code
+  used in Sucrase, and can be run using `yarn generate`.
+* The `benchmark` directory contains some some simple benchmarks, which can be
+  run with `yarn benchmark`.
+* The `script` directory has all build scripts (written in TypeScript and
+  compiled with Sucrase).

README.md

@@ -159,6 +159,9 @@ to have nearly the scope and versatility of Babel. Some specific examples:
   mostly beneficial in development, and in many cases, Babel or tsc will be more
   suitable for production builds.
 
+See the [Project Vision](./docs/PROJECT_VISION.md) document for more details on
+the philosophy behind Sucrase.
+
 ## Motivation
 
 As JavaScript implementations mature, it becomes more and more reasonable to
@@ -205,40 +208,11 @@ TypeScript: 3782.414ms
 Babel: 9591.515ms
 ```
 
-## Project vision and future work
-
-### Performance improvements
-
-* Rewrite the code to run in WebAssembly, either by changing it to be valid
-  [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) or by
-  rewriting it in Rust.
-* Explore the idea of a JIT to optimize the various token patterns that need to
-  be matched as part of code transformation.
-
-### New features
-
-* Implement more integrations, like a Browserify plugin.
-* Emit proper source maps. (The line numbers already match up, but this would
-  help with debuggers and other tools.)
-* Rethink configuration and try to simplify it as much as possible, and allow
-  loading Babel/TypeScript configurations.
-* Explore the idea of a tool that patches a Babel/TypeScript installation to
-  use Sucrase instead, to make it even easier to try Sucrase on an existing
-  codebase.
-* Explore the idea of extending this approach to other tools, e.g. module
-  bundlers.
-
-### Correctness and stability
-
-* Add more open source projects to the suite of projects that are tested
-  automatically.
-* Set up a test suite that runs the compiled code and ensures that it is
-  correct.
-* Add integrity checks to compare intermediate Sucrase results (like tokens and
-  the role of each identifier and pair of curly braces) with the equivalent
-  information from Babel.
-* Fix some known correctness loose ends, like import hoisting and fully
-  replicating the small differences between Babel and the TypeScript compiler.
+## Contributing
+
+Contributions are welcome, whether they be bug reports, PRs, docs, tests, or
+anything else! Please take a look through the [Contributing Guide](./CONTRIBUTING.md)
+to learn how to get started.
 
 ## License and attribution
 

docs/PROJECT_VISION.md

@@ -0,0 +1,95 @@
+# Project Vision
+
+This is a collection of little essays that help solidify and communicate what
+this project is all about. Ultimately, every project needs to say "no" to some
+features, and keeping a small scope is particularly important for Sucrase. My
+hope is that these notes help guide and clarify those sorts of decisions.
+
+All of these are open to discussion! It's written in first person for now, but
+it may later make sense to make the phrasing more general.
+
+## Sucrase exists to make programming more fun
+
+This is probably true of most tools, but I want to call it out explicitly: I
+started Sucrase because it seemed like there was an opportunity for me to be
+happier when programming. I was running into some specific problems that I felt
+could be improved:
+* Build times can be slow, and in many (but not all) scenarios, Babel and tsc
+  are a big part of that.
+* Slow build times mean that we use caches, and caches can be fragile. It's
+  frustrating to realize that a problem might be caused by bad cache, and to
+  make things worse, checking if that was the problem requires doing a slow
+  clean build.
+* Slow build times means slow iteration times, especially when running tests. A
+  great programming experience is one where you feel free to tinker with any
+  part of the code to see what happens.
+
+Programming is fun when tools get out of the way. They should be fast, they
+should be reliable, and they should be simple (e.g. no configuration needed). I
+want all tools to be like that, and hopefully Sucrase is a step in that
+direction.
+
+## Sucrase is an experiment
+
+The secondary reason I started Sucrase was to learn and to try new things. I had
+an idea on how to improve build times, but I *didn't know* if it was going to
+work, and I still don't know the best way to implement it. Sucrase's development
+ideally should consist largely of trying new ideas and keeping the ones that
+work well.
+
+For example, WebAssembly support is an important future goal of Sucrase, and it
+may involve reworking a fair amount of code just to try it out, and it may end
+up as a failed experiment, which is ok. There may also be breaking changes in
+Sucrase (which will be properly released as semver-major updates). At least for
+now, there needs to be some flexibility to play around with ideas without
+worrying about staying backcompat forever.
+
+## Sucrase is not meant to replace Babel
+
+A worry of mine in releasing Sucrase is that it might someday become popular
+enough to detract from the great efforts that have been put into Babel. Babel
+isn't just a build tool, it's a mechanism for language exploration and
+prototyping, and it enables new programming possibilities. Sucrase takes the
+best of those and rewrites them to be fast, but Sucrase isn't a great mechanism
+for exploration and will never reach as far forward in syntax or as far backward
+in compatibility as Babel does.
+
+## Sucrase should push tooling forward
+
+Sucrase won't support Node 6 or Internet Explorer, and only reluctantly supports
+CommonJS and legacy TypeScript and Babel 5 module interop (and may drop support
+in the future). In various other build system decisions, there's often "the old
+way of doing things" and "the modern way of doing things", and Sucrase prefers
+to only support the modern way. This lets Sucrase stay simple and helps motivate
+people to modernize their build system and codebase. The longer we hold onto old
+technologies, the more intimidating it will be for people trying to learn and
+understand the JS ecosystem, so Sucrase tries to push for consistency and
+simplicity.
+
+## Sucrase is small, and thus is allowed to be complicated
+
+Large software systems can stay maintainable by using well-chosen abstractions
+and code organization, sometimes at the expense of performance. Sucrase takes a
+different approach: it biases toward performance (even if it makes the code
+harder to work with) and stays maintainable by keeping the scope small.
+
+As one example, the Babel parser does a significant amount of work validating
+the input code and building an AST, and Sucrase intentionally skips all
+validation and AST generation, which reduces the parser code by about 50%. As
+another example, Sucrase code transformations are not composable and
+independent, and plugins are not supported, since the flexibility of such a
+system would ultimately come at the expense of performance.
+
+## Sucrase favors pragmatism over strict spec compliance
+
+The JS language has various obscure edge cases that make implementation more
+difficult, and in some cases, Sucrase may decide to go against the spec because
+the issue is so obscure. For example, variable names are allowed to have unicode
+escapes in them, so `const \u0061 = 1; console.log(a);` prints 1. Other details
+may require significant extra information from the parser, slowing down even the
+common case. Sucrase's goal is to work on all realistic code, and it goes to
+great effort to ensure that, but some code is so unrealistic that it's not worth
+supporting.
+
+In unsupported cases, ideally Sucrase will either give an error or provide an
+ESLint rule that detects and warns against the case.