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

This commit is contained in:
Angus Gratton 2016-09-21 17:25:36 +10:00
parent 79c21895d0
commit 22e99694e3
3 changed files with 88 additions and 2 deletions

37
CONTRIBUTING.md Normal file
View file

@ -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.

View file

@ -1,6 +1,18 @@
# Using Espressif IoT Development Framework with the ESP32 # 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 # Configuring your project
@ -52,8 +64,10 @@ For more details about partition tables and how to create custom variations, vie
# Resources # 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. * 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. * [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.

35
examples/README.md Normal file
View file

@ -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.