Documentation: Add contributor guide, expand README & add an examples README

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributions Guide
+
+We welcome contributions to the esp-idf project!
+
+## How to Contribute
+
+Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via the [Github Pull Request](https://help.github.com/articles/about-pull-requests/) feature.
+
+## Before Contributing
+
+Before sending us a Pull Request, please consider this list of points:
+
+* Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we cannot accept it.
+
+* Does any new code conform to the esp-idf Style Guide? (Style Guide currently pending).
+
+* Is the code adequately commented for people to understand how it is structured?
+
+* Is there documentation or examples that go with code contributions? [There are additional suggestions for writing good examples in the examples README](examples/README.md).
+
+* Are comments and documentation written in clear English, with no spelling or grammar errors?
+
+* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" squashed into previous commits?
+
+* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
+
+## Pull Request Process
+
+After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
+
+Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.
+
+If this process passes, it will be merged onto the public github repository.
+
+## Legal Part
+
+Before a contribution is accepted, you will need to sign our Contributor Agreement. You will be prompted for this automatically as part of the Pull Request process.

README.md

@@ -1,6 +1,18 @@
 # Using Espressif IoT Development Framework with the ESP32
 
-# Prerequisites
+# Setting Up ESP-IDF
+
+In the [docs](docs) directory you will find per-platform setup guides:
+
+* [Windows Setup Guide](docs/windows-setup.rst)
+* [Mac OS Setup Guide](docs/macos-setup.rst)
+* [Linux Setup Guide](docs/linux-setup.rst)
+
+# Finding A Project
+
+As well as the [esp-idf-template](https://github.com/espressif/esp-idf-template) project mentioned in the setup guide, esp-idf comes with some example projects in the [examples](examples) directory.
+
+Once you've found the project you want to work with, change to its directory and you can configure and build it:
 
 # Configuring your project
 
@@ -52,8 +64,10 @@ For more details about partition tables and how to create custom variations, vie
 
 # Resources
 
-* The [docs directory of the esp-idf repository](https://github.com/espressif/esp-idf/tree/master/docs) contains esp-idf documentation.
+* The [docs directory of the esp-idf repository](docs) contains esp-idf documentation.
 
 * The [esp32.com forum](http://esp32.com/) is a place to ask questions and find community resources.
 
 * [Check the Issues section on github](https://github.com/espressif/esp-idf/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one.
+
+* If you're interested in contributing to esp-idf, please check the [CONTRIBUTING.md](CONTRIBUTING.md) file.

examples/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+This directory contains a growing number of simple example projects for esp-idf. These are intended to show basic esp-idf functionality, and to provide you can use for your own projects.
+
+# Using Examples
+
+Building examples is the same as building any other project:
+
+* Follow the setup instructions in the top-level esp-idf README.
+
+* Set `IDF_PATH` environment variable to point to the path to the esp-idf top-level directory.
+* Change into the directory of the example you'd like to build.
+* `make menuconfig` to configure the example. Most examples require a simple WiFi SSID & password via this configuration.
+* `make` to build the example.
+* Follow the printed instructions to flash, or run `make flash`.
+
+# Copying Examples
+
+Each example is a standalone project. The examples *do not have to be inside the esp-idf directory*. You can copy an example directory to anywhere on your computer in order to make a copy that you can modify and work with.
+
+The `IDF_PATH` environment variable is the only thing that connects the example to the rest of the `esp-idf` system.
+
+If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template).
+
+# Contributing Examples
+
+If you have a new example you think we'd like, please consider sending it to us as a Pull Request.
+
+Please read the esp-idf CONTRIBUTING.md file which lays out general contribution rules.
+
+In addition, here are some tips for creating good examples:
+
+* A good example is documented and the basic options can be configured.
+* A good example does not contain a lot of code. If there is a lot of generic code in the example, consider refactoring that code into a standalone component and then use the component's API in your example.
+* Examples must be licensed under the Apache License 2.0 or (preferably for examples) if possible you can declare the example to be Public Domain / Creative Commons Zero.