merge

docs/general/contributing.md

@@ -0,0 +1,136 @@
+# Contributing
+
+Want to contribute to Slate? That would be awesome!
+
+- [Contributing](contributing.md#contributing)
+  - [Reporting Bugs](contributing.md#reporting-bugs)
+  - [Asking Questions](contributing.md#asking-questions)
+  - [Submitting Pull Requests](contributing.md#submitting-pull-requests)
+  - [Repository Setup](contributing.md#repository-setup)
+  - [Running Examples](contributing.md#running-examples)
+  - [Running Tests](contributing.md#running-tests)
+  - [Testing Input Methods](contributing.md#testing-input-methods)
+  - [Publishing Releases](contributing.md#publishing-releases)
+    - [Publishing Normal `@latest` Release](contributing.md#publishing-normal-latest-release)
+    - [Publishing `@next` Release](contributing.md#publishing-next-release)
+    - [Publishing `@experimental` Release](contributing.md#publishing-experimental-release)
+    - [Running Prerelease Script](contributing.md#running-prerelease-script)
+
+## Reporting Bugs
+
+If you run into any weird behavior while using Slate, feel free to open a new issue in this repository! Please run a **search before opening** a new issue, to make sure that someone else hasn't already reported or solved the bug you've found.
+
+Any issue you open must include:
+
+- A [JSFiddle](https://jsfiddle.net/01pLxfzu/) that reproduces the bug with a minimal setup.
+- A GIF showing the issue in action. \(Using something like [RecordIt](http://recordit.co/).\)
+- A clear explanation of what the issue is.
+
+Here's a [JSFiddle template for Slate](https://jsfiddle.net/01pLxfzu/) to get you started:
+
+[![](../.gitbook/assets/jsfiddle.png)](https://jsfiddle.net/01pLxfzu/)
+
+## Asking Questions
+
+We've also got a [Slate Slack team](https://slate-slack.herokuapp.com) where you can ask questions and get answers from other people using Slate:
+
+[![](../.gitbook/assets/slack.png)](https://slate-slack.herokuapp.com)
+
+Please use the Slack instead of asking questions in issues, since we want to reserve issues for keeping track of bugs and features. We close questions in issues so that maintaining the project isn't overwhelming.
+
+## Submitting Pull Requests
+
+All pull requests are super welcomed and greatly appreciated! Issues in need of a solution are marked with a [`♥ help`](https://github.com/ianstormtaylor/slate/issues?q=is%3Aissue+is%3Aopen+label%3A%22%E2%99%A5+help%22) label if you're looking for somewhere to start.
+
+Please include tests and docs with every pull request!
+
+## Repository Setup
+
+The slate repository is a monorepo that is managed with [lerna](https://github.com/lerna/lerna). Unlike more traditional repositories, this means that the repository must be built in order for tests, linting, or other common development activities to function as expected.
+
+To run the build, you need to have the Slate repository cloned to your computer. After that, you need to `cd` into the directory where you cloned it, and install the dependencies with `yarn` and build the monorepo:
+
+```text
+yarn install
+yarn build
+```
+
+## Running Examples
+
+To run the examples, start by building the monorepo as described in the [Repository Setup](contributing.md#repository-setup) section.
+
+Then you can start the examples server with:
+
+```text
+yarn start
+```
+
+## Running Tests
+
+To run the tests, start by building the monorepo as described in the [Repository Setup](contributing.md#repository-setup) section.
+
+Then you can rerun the tests with:
+
+```text
+yarn test
+```
+
+If you need to debug something, you can add a `debugger` line to the source, and then run `yarn test:inspect`.
+
+If you only want to run a specific test or tests, you can run `yarn test --fgrep="slate-react rendering"` flag which will filter the tests being run by grepping for the string in each test. \(This is a Mocha flag that gets passed through.\)
+
+In addition to tests you should also run the linter:
+
+```text
+yarn lint
+```
+
+This will catch TypeScript, Prettier, and Eslint errors.
+
+## Testing Input Methods
+
+[Here's a helpful page](https://github.com/Microsoft/vscode/wiki/IME-Test) detailing how to test various input scenarios on Windows, Mac and Linux.
+
+## Publishing Releases
+
+**Important**: When creating releases using Lerna with the instructions below, you will be given choices around how to increase version numbers. You should always use a `major`, `minor` or `patch` release and must never use a `prerelease`. If a prerelease is used, the root package will not link to the packages in the `packages` directory creating hard to diagnose issues.
+
+### Publishing Normal `@latest` Release
+
+Since we use [Lerna](https://lerna.js.org) to manage the Slate packages this is fairly easy, just run:
+
+```text
+yarn release:latest
+```
+
+And follow the prompts Lerna gives you.
+
+Note that this will automatically run the prelease script first that will build, test and lint before attempting to publish.
+
+### Publishing `@next` Release
+
+If we are unsure as to the stability of a release because there are significant changes and/or particularly complex changes, release with the `@next` tag.
+
+```text
+yarn release:next
+```
+
+And follow the prompts Lerna gives you.
+
+### Publishing `@experimental` Release
+
+If you need to create an experimental release to see how a published package will behave during an actual publish, release with the `@experimental` tag. End users should have no expectation that an `@experimental` release will be usable.
+
+```text
+yarn release:experimental
+```
+
+### Running Prerelease Script
+
+If we want to make sure that Slate code follows the preparations for a release but without actually publishing, run:
+
+```text
+yarn prerelease
+```
+
+Which will build, test and lint Slate code.

docs/general/faq.md

@@ -2,22 +2,22 @@
 
 A series of common questions people have about Slate:
 
-- [Why is content pasted as plain text?](#why-is-content-is-pasted-as-plaintext)
-- [What can a `Block` node have as its children?](#what-can-a-block-node-have-as-its-children)
-- [What browsers and devices does Slate support?](#what-browsers-and-devices-does-slate-support)
+- [Why is content pasted as plain text?](faq.md#why-is-content-is-pasted-as-plaintext)
+- [What can a `Block` node have as its children?](faq.md#what-can-a-block-node-have-as-its-children)
+- [What browsers and devices does Slate support?](faq.md#what-browsers-and-devices-does-slate-support)
 
-### Why is content pasted as plain text?
+## Why is content pasted as plain text?
 
 One of Slate's core principles is that, unlike most other editors, it does **not** prescribe a specific "schema" to the content you are editing. This means that Slate's core has no concept of "block quotes" or "bold formatting".
 
 For the most part, this leads to increased flexbility without many downsides, but there are certain cases where you have to do a bit more work. Pasting is one of those cases.
 
-Since Slate knows nothing about your domain, it can't know how to parse pasted HTML content (or other content). So, by default whenever a user pastes content into a Slate editor, it will parse it as plain text. If you want it to be smarter about pasted content, you need to override the `insert_data` command and deserialize the `DataTransfer` object's `text/html` data as you wish.
+Since Slate knows nothing about your domain, it can't know how to parse pasted HTML content \(or other content\). So, by default whenever a user pastes content into a Slate editor, it will parse it as plain text. If you want it to be smarter about pasted content, you need to override the `insert_data` command and deserialize the `DataTransfer` object's `text/html` data as you wish.
 
-### What browsers and devices does Slate support?
+## What browsers and devices does Slate support?
 
 Slate's goal is to support all the modern browsers on both desktop and mobile devices.
 
-However, right now Slate is in beta and is community-driven, so its support is not as robust as it could be. It's currently tested against the latest few versions of Chrome, Edge, Firefox and Safari on desktops. And it does not work in Internet Explorer. On mobile, iOS devices are supported but not regularly tested. Chrome on Android is supported on Slate 0.47 but is not currently supported in Slate 0.50+ though there is currently work being done on one (https://github.com/ianstormtaylor/slate/issues/3786). If you want to add more browser or device support, we'd love for you to submit a pull request! Or in the case of incompatible browsers, build a plugin.
+However, right now Slate is in beta and is community-driven, so its support is not as robust as it could be. It's currently tested against the latest few versions of Chrome, Edge, Firefox and Safari on desktops. And it does not work in Internet Explorer. On mobile, iOS devices are supported but not regularly tested. Chrome on Android is supported on Slate 0.47 but is not currently supported in Slate 0.50+ though there is currently work being done on one \([https://github.com/ianstormtaylor/slate/issues/3786](https://github.com/ianstormtaylor/slate/issues/3786)\). If you want to add more browser or device support, we'd love for you to submit a pull request! Or in the case of incompatible browsers, build a plugin.
 
-For older browsers, such as IE11, a lot of the now standard native APIs aren't available. Slate's position on this is that it is up to the user to bring polyfills (like https://polyfill.io) when needed for things like `el.closest`, etc. Otherwise we'd have to bundle and maintain lots of polyfills that others may not even need in the first place. For clarity, Slate makes no guarantees that it will work with older browsers, even with polyfills and at present, there are still unresolved issues with IE11.
+For older browsers, such as IE11, a lot of the now standard native APIs aren't available. Slate's position on this is that it is up to the user to bring polyfills \(like [https://polyfill.io](https://polyfill.io)\) when needed for things like `el.closest`, etc. Otherwise we'd have to bundle and maintain lots of polyfills that others may not even need in the first place. For clarity, Slate makes no guarantees that it will work with older browsers, even with polyfills and at present, there are still unresolved issues with IE11.

docs/general/resources.md

@@ -6,7 +6,7 @@ A few resources that are helpful for building with Slate.
 
 These libraries are helpful when developing with Slate:
 
-- [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) is a simple way to check whether an `onKeyDown` handler should fire for a given hotkey, handling cross-platform concerns like <kbd>cmd</kbd> vs. <kbd>ctrl</kbd> keys for you automatically.
+- [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) is a simple way to check whether an `onKeyDown` handler should fire for a given hotkey, handling cross-platform concerns like cmd vs. ctrl keys for you automatically.
 
 ## Products
 
@@ -45,4 +45,4 @@ These pre-packaged editors are built on top of Slate, and can be helpful to see
 - [React Force Slate Editor](https://github.com/nareshbhatia/react-force/tree/master/packages/slate-editor) is a light-weight medium-style editor with no editor chrome.
 - [Slate Plugins Next](https://github.com/zbeyens/slate-plugins-next) provides an editor with configurable and extendable plugins.
 
-(Or, if you have their exact use case, can be a drop-in editor for you.)
+\(Or, if you have their exact use case, can be a drop-in editor for you.\)