From 22e99694e3c7711a1e3a758d358147f07c1c848e Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 21 Sep 2016 17:25:36 +1000 Subject: [PATCH] Documentation: Add contributor guide, expand README & add an examples README --- CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++ README.md | 18 ++++++++++++++++-- examples/README.md | 35 +++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 examples/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..824ec6ff3 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 10fd72a3c..ff645c339 100644 --- a/README.md +++ b/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. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..2cf66b9d0 --- /dev/null +++ b/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.