Documentation: reorganize current docs and create new ones. (Automattic#5985)

* Documentation: reorganize current docs and create new ones.

- Make contributing less frightening and easier for all potential contributors.
- Make our guidelines and requirements clearer.
- Surface all data in our contributing guide.
- Offer options to contribute to everyone, even if it's not via code.
- Outline our release management process, and approach to code reviews and Pull Requests.

* Documentation: fix typos, headings, wrong links.

* Add PHPCS and ESLint to the development environment documentation.

* Docs: include some information about PHP Unit Testing.

Fixes Automattic#6236

* Docs: add "Development" section.

@see Automattic#5985 (comment)

Author: jeherve

Diff for: .github/CONTRIBUTING.md

@@ -14,70 +14,17 @@ Beta testers give updates, fixes, and new modules a test run before they’re pu
 
 If you find a bug, just [file a GitHub issue](https://github.com/Automattic/jetpack/issues/), that’s all. If you want to prefix the title with a “Question:”, “Bug:”, or the general area of the application, that would be helpful, but by no means mandatory. If you have write access, add the appropriate labels.
 
-If you’re filing a bug, specific steps to reproduce are helpful. Please include the URL of the page that has the bug, along with what you expected to see and what happened instead. You can [check our recommendations to create great bug reports here](http://jetpack.com/contribute/#bugs).
+If you’re filing a bug, specific steps to reproduce are helpful. Please include the URL of the page that has the bug, along with what you expected to see and what happened instead. You can [check our recommendations to create great bug reports here](/docs/guides/report-bugs.md).
 
-### Write and submit a patch
-
-If you'd like to fix a bug, you can submit a Pull Request. [Follow these detailed steps to find out how](http://jetpack.com/contribute/#patch).
-
-When creating Pull Requests, remember:
-
-- [Check In Early, Check In Often](http://blog.codinghorror.com/check-in-early-check-in-often/).
-- Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
-- Respect the [Best practices for WordPress development](http://jetpack.com/contribute/#practices).
-
-#### Code Reviews
-
-Code reviews are an important part of the Jetpack workflow. They help to keep code quality consistent, and they help every person working on Jetpack learn and improve over time. We want to make you the best Jetpack contributor you can be.
-
-Every PR should be reviewed and approved by someone other than the author, even if the author has write access. Fresh eyes can find problems that can hide in the open if you’ve been working on the code for a while.
-
-The recommended way of finding an appropriate person to review your code is by [blaming](https://help.github.com/articles/using-git-blame-to-trace-changes-in-a-file/) one of the files you are updating and looking at who was responsible for previous commits on that file.
-
-Then, you may ask that person to review your code by mentioning his/her GitHub username on the PR comments like this:
-
-```
- cc @username
-```
-
-*Everyone* is encouraged to review PRs and add feedback and ask questions, even people who are new to Jetpack. Also, don’t just review PRs about what you’re working on. Reading other people’s code is a great way to learn new techniques, and seeing code outside of your own feature helps you to see patterns across the project. It’s also helpful to see the feedback other contributors are getting on their PRs.
-
-#### Coding Standards & Guidelines
+### Translate the plugin
 
-Consistent coding style makes the code so much easier to read. Here are ours:
+If you speak a foreign language, you can help translate Jetpack into your own language. [here is how.](/docs/translations.md)
 
-- If you've created a new action or filter, [add inline documentation](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters) to help others understand how to use the action or the filter.
-- Create [unit tests](https://github.com/Automattic/jetpack/tree/master/tests) if you can. If you're not familiar with Unit Testing, you can check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/).
-- If [Gulp](http://gulpjs.com/) is installed on your testing environment, run it after committing your changes. It will allow you to [detect errors in Javascript files](http://jshint.com/about/), compile Sass to CSS, and [a few other things](https://github.com/Automattic/jetpack/blob/master/gulpfile.js).
-
-#### Lifecycle of a Pull Request
-
-When you’re first starting out, your natural instinct when creating a new feature will be to create a local feature branch, and start building away. If you start doing this, *stop*, take your hands off the keyboard, grab a coffee and read on. :)
-
-**It’s important to break your feature down into small pieces first**, each piece should become its own pull request.
-
-Once you know what the first small piece of your feature will be, follow this general process while working:
-
-1. Create a new branch, using [the branch naming scheme](https://github.com/Automattic/jetpack/wiki/Git-Workflow#branch-naming-scheme), _e.g._ `add/video-preview` or `fix/1337-language-too-geeky`.
-2. Make your first commit: any will do even if empty or trivial, but we need something in order to create the initial pull request. Create the pull request and prefix the name with the section of the product, _e.g._ _Sharing: add new Facebook button_. Don’t worry too much if there’s no obvious prefix.
-  - Write a detailed description of the problem you are solving, the part of Jetpack it affects, and how you plan on going about solving it.
-  - If you have write access, add the **<span class="label status-in-progress">[Status] In Progress</span>** label or wait until somebody adds it. This indicates that the pull request isn’t ready for a review and may still be incomplete. On the other hand, it welcomes early feedback and encourages collaboration during the development process.
-3. Start developing and pushing out commits to your new branch.
-  - Push your changes out frequently and try to avoid getting stuck in a long-running branch or a merge nightmare. Smaller changes are much easier to review and to deal with potential conflicts.
-  - Don’t be afraid to change, [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html), and rearrange commits or to force push - `git push -f origin fix/something-broken`. Keep in mind, however, that if other people are committing on the same branch then you can mess up their history. You are perfectly safe if you are the only one pushing commits to that branch.
-  - Squash minor commits such as typo fixes or [fixes to previous commits](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) in the pull request.
-4. If you end up needing more than a few commits, consider splitting the pull request into separate components. Discuss in the new pull request and in the comments why the branch was broken apart and any changes that may have taken place that necessitated the split. Our goal is to catch early in the review process those pull requests that attempt to do too much.
-5. When you feel that you are ready for a formal review or for merging into `master` make sure you check this list.
-  - Make sure your branch merges cleanly and consider rebasing against `master` to keep the branch history short and clean.
-  - If there are visual changes, add before and after screenshots in the pull request comments.
-  - Add unit tests, or at a minimum, provide helpful instructions for the reviewer so he or she can test your changes. This will help speed up the review process.
-  - Ensure that your commit messages are [meaningful](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
-6. Mention that the PR is ready for review or if you have write access remove the **<span class="label status-in-progress">[Status] In Progress</span>** label from the pull request and add the **<span class="label status-needs-review">[Status] Needs Review</span>** label - someone will provide feedback on the latest unreviewed changes. The reviewer will also mark the pull request as **<span class="label needs-author-reply">[Status] Needs Author Reply</span>** if they think you need to change anything.
-7. If you get a <img src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f44d.png" class="emoji" />, <img src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f4a5.png" class="emoji" />, <img src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f6a2.png" class="emoji" />, <img src="https://assets-cdn.github.com/images/icons/emoji/shipit.png" class="emoji" />, or a LGTM, the pull request is ready to be merged into `master`.
+### Write and submit a patch
 
-Whether somebody is reviewing your code or you are reviewing somebody else’s code, [a positive mindset towards code reviews](https://medium.com/medium-eng/the-code-review-mindset-3280a4af0a89) helps a ton. We’re building something together that is greater than the sum of its parts.
+If you'd like to fix a bug, you can submit a Pull Request. Before you get started, you'll want to **[set up your development environment.](/docs/development-environment.md)**
 
-If you feel yourself waiting for someone to review a PR, don’t hesitate to personally ask for someone to review it or to mention them on GitHub.
+Once your development environment is ready, you can get started and [create your first Pull Request!](/docs/pull-request.md)
 
 #### Where to get started?
 
@@ -87,6 +34,17 @@ If you'd like to contribute but don't know where to get started, you can take a
 - All issues labeled with [the "Community" milestone](https://github.com/Automattic/jetpack/issues?q=is%3Aopen+is%3Aissue+milestone%3ACommunity) are fair game. That's a great way to contribute new features and fix small issues within Jetpack.
 - ["Whisky"](https://github.com/Automattic/jetpack/labels/Whisky%20Ticket) issues are important bugs or enhancements. Take a crack at it if you feel adventurous! :)
 
+Are you new to Git? You can [follow these detailed steps to find out how to submit your first patch.](/docs/guides/submit-patch.md)
+
 #### We’re Here To Help
 
-We encourage you to ask for help at any point. We want your first experience with Jetpack to be a good one, so don’t be shy. If you’re wondering why something is the way it is, or how a decision was made, you can tag issues with **<span class="label type-question">[Type] Question</span>** or prefix them with “Question:”.
+We encourage you to ask for help at any point. We want your first experience with Jetpack to be a good one, so don’t be shy. If you’re wondering why something is the way it is, or how a decision was made, you can create an issue and prefix it with “Question:”.
+
+## License
+
+Jetpack is licensed under [GNU General Public License v2 (or later)](/LICENSE.md).
+
+All materials contributed should be compatible with the GPLv2. This means that if you own the material, you agree to license it under the GPLv2 license. If you are contributing code that is not your own, such as adding a component from another Open Source project, or adding an `npm` package, you need to make sure you follow these steps:
+
+1. Check that the code has a license. If you can't find one, you can try to contact the original author and get permission to use, or ask them to release under a compatible Open Source license.
+2. Check the license is compatible with [GPLv2](http://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses), note that the Apache 2.0 license is *not* compatible.

Diff for: .github/PULL_REQUEST_TEMPLATE.md

@@ -2,17 +2,11 @@ Fixes #
 
 #### Changes proposed in this Pull Request:
 
+*
 
 #### Testing instructions:
 
 *
 
 <!-- Add the following only if this is meant to be in changelog -->
 #### Proposed changelog entry for your changes:
-
-
--------------------
-- [ ] Make sure your changes respect [WordPress' coding standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/).
-- [ ] Did you make changes, or create a **new .js file**? If [Gulp](http://gulpjs.com/) is installed on your testing environment, run `gulp js:hint` before to commit your changes. It will allow you to [detect errors in Javascript files](http://jshint.com/about/).
-- [ ] Did you create a **new action or filter**? [Add inline documentation](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters) to help others understand how to use the action or the filter.
-- [ ] Create **[unit tests](https://github.com/Automattic/jetpack/tree/master/tests)** if you can. If you're not familiar with Unit Testing, you can check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/).

Diff for: .svnignore

@@ -7,6 +7,7 @@
 readme.md
 .github
 phpunit.xml.dist
+docs
 tests
 tools
 package.json

Diff for: CODE-OF-CONDUCT.md

@@ -0,0 +1,28 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+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.
+
+By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing a project maintainer via [this contact form](https://developer.wordpress.com/contact/?g21-subject=Code%20of%20Conduct), with a subject that includes `Code of Conduct`. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident.
+
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.3.0, available at [http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

Diff for: docs/code-reviews.md

@@ -0,0 +1,17 @@
+# Code Reviews
+
+Code reviews are an important part of the Jetpack workflow. They help to keep code quality consistent, and they help every person working on Jetpack learn and improve over time. We want to make you the best Jetpack contributor you can be.
+
+Every PR should be reviewed and approved by someone other than the author, even if the author has write access. Fresh eyes can find problems that can hide in the open if you’ve been working on the code for a while.
+
+The recommended way of finding an appropriate person to review your code is by [blaming](https://help.github.com/articles/using-git-blame-to-trace-changes-in-a-file/) one of the files you are updating and looking at who was responsible for previous commits on that file.
+
+Then, you may ask that person to review your code by mentioning his/her GitHub username on the PR comments like this:
+
+```
+ cc @username
+```
+
+*Everyone* is encouraged to review PRs and add feedback and ask questions, even people who are new to Jetpack. Also, don’t just review PRs about what you’re working on. Reading other people’s code is a great way to learn new techniques, and seeing code outside of your own feature helps you to see patterns across the project. It’s also helpful to see the feedback other contributors are getting on their PRs.
+
+Whether somebody is reviewing your code or you are reviewing somebody else’s code, [a positive mindset towards code reviews](https://medium.com/medium-eng/the-code-review-mindset-3280a4af0a89) helps a ton. We’re building something together that is greater than the sum of its parts.

Diff for: docs/coding-guidelines.md

@@ -0,0 +1,27 @@
+# Coding Standards & Guidelines
+
+These are some things to keep in mind when writing code for Jetpack plugin. Please follow them to speed up the review process and get your code merged faster.
+
+### Versions supported
+
+- Jetpack supports PHP 5.2, so to name two examples, don't use array notation like `[]` or the short ternary like `expr1 ?: expr3`: use always `array()` and the long ternary `expr1 ? expr2: expr3`.
+- Jetpack supports the WP current version and the immediate previous version. So if WP version is 4.6, Jetpack will support it, as well as 4.5. It's desirable that when Jetpack is installed in older versions, it doesn't fail in a severe way.
+
+### General
+
+- Install PHP Code Sniffer [Code Sniffer rules for WordPress Coding Standards.](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#installation) They will make it easier for you to notice any missing documentation or coding standards you should respect. Most IDEs display warnings and notices inside the editor, making it easy to inspect your code.
+- If coding a module, make sure you declare the module in the inline doc, [like this](https://github.com/Automattic/jetpack/blob/16bc2fce3ace760ff402f656dcf05255888f23f4/modules/sitemaps/sitemaps.php#L92-L101). The same applies for filters or actions, [as shown here](https://github.com/Automattic/jetpack/blob/16bc2fce3ace760ff402f656dcf05255888f23f4/modules/sitemaps/sitemaps.php#L143-L151).
+- Sanitize URLs, attributes, everything. WordPress.com VIP has this nice [article about the topic](https://vip.wordpress.com/documentation/vip/best-practices/security/validating-sanitizing-escaping/).
+- Create [unit tests](https://github.com/Automattic/jetpack/tree/master/tests) if you can. If you're not familiar with Unit Testing, you can check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/).
+
+### Widgets
+
+- Make them support Customizer's Selective Refresh. Here's an [article about it](https://make.wordpress.org/core/2016/03/22/implementing-selective-refresh-support-for-widgets/).
+- Some Widgets ported from WordPress.com must only be registered if Jetpack is connected.
+- Add the `jetpack_widget_name` filter to the widget title [as shown here](https://github.com/Automattic/jetpack/blob/447766aa676dfc78822d33af4f73535668eba063/modules/widgets/my-community.php#L37).
+
+### Translations
+
+- Where it applies, make strings available for translation.
+- Instead of `__`, `_e`, `_x` and similar functions, use their safe versions `esc_html__`, `esc_html_e`, `esc_html_x` and others where possible.
+- Add the `jetpack` text domain to the translation functions.