docs: make CONTRIBUTING.md readable on Github

Move the contents of CONTRIBUTING.rst into contributing/index.rst, create CONTRIBUTING.md with a link to the programming guide. Closes #6807
espressif · May 3, 2022 · 0f515ce · 0f515ce
1 parent b5c99bc
commit 0f515ce
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 72 deletions.
diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS
@@ -53,7 +53,7 @@
 /.pre-commit-config.yaml              @esp-idf-codeowners/ci
 /.readthedocs.yml                     @esp-idf-codeowners/docs
 /CMakeLists.txt                       @esp-idf-codeowners/build-config
-/CONTRIBUTING.rst                     @esp-idf-codeowners/docs
+/CONTRIBUTING.md                      @esp-idf-codeowners/docs
 /Kconfig                              @esp-idf-codeowners/build-config
 /README*.md                           @esp-idf-codeowners/docs
 /add_path.sh                          @esp-idf-codeowners/tools

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,6 @@
+# Contributing to ESP-IDF
+
+Contributions to ESP-IDF - fixing bugs, adding features, adding documentation - are welcome! We accept contributions via Github Pull Requests.
+
+Please see the [Contributions Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/index.html) for more information.
+
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
diff --git a/docs/en/contribute/contributor-agreement.rst b/docs/en/contribute/contributor-agreement.rst
@@ -1,19 +1,15 @@
 Contributor Agreement
 =====================
 
-Individual Contributor Non-Exclusive License Agreement
-------------------------------------------------------
-
-including the Traditional Patent License OPTION
------------------------------------------------
+Individual Contributor Non-Exclusive License Agreement including the Traditional Patent License OPTION
+------------------------------------------------------------------------------------------------------
 
 Thank you for your interest in contributing to Espressif IoT Development
 Framework (esp-idf) ("We" or "Us").
 
 The purpose of this contributor agreement ("Agreement") is to clarify
 and document the rights granted by contributors to Us. To make this
-document effective, please follow the instructions at
-:idf_file:`CONTRIBUTING.rst`
+document effective, please follow the instructions in the :doc:`index`.
 
 1. DEFINITIONS
 ~~~~~~~~~~~~~~

diff --git a/docs/en/contribute/index.rst b/docs/en/contribute/index.rst
@@ -1 +1,63 @@
-.. include:: ../../../CONTRIBUTING.rst
+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 `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
+
+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 unfortunately cannot accept it. Please check the :doc:`Copyright Header Guide <copyright-guide>` for additional information.
+
+* Does any new code conform to the esp-idf :doc:`Style Guide <style-guide>`?
+
+* Have you installed the :doc:`pre-commit hook <install-pre-commit-hook>` for esp-idf project?
+
+* Does the code documentation follow requirements in :doc:`documenting-code`?
+
+* 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 :idf:`examples` readme.
+
+* Are comments and documentation written in clear English, with no spelling or grammar errors?
+
+* Example contributions are also welcome. Please check the :doc:`creating-examples` guide for these.
+
+* 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 <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
+
+* 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 can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process.
+
+Related Documents
+-----------------
+
+.. toctree::
+    :maxdepth: 1
+
+    style-guide
+    install-pre-commit-hook
+    documenting-code
+    creating-examples
+    ../api-reference/template
+    contributor-agreement
+    copyright-guide
+    esp-idf-tests-with-pytest